Add backend support for real-time in-room text chat

[Muneerali199]

🚀 The feature

Resonate currently supports real-time voice rooms, but there is no backend infrastructure to support text-based communication within rooms.

This proposal introduces backend support for real-time in-room text chat, enabling clients to send, receive, and moderate text messages during active voice rooms.

This issue complements the frontend feature request opened in the Resonate app repository for in-room text chat.

---

Problem statement

At present:

• There is no backend mechanism to handle real-time text messages in rooms
• Messages cannot be persisted or synchronized across participants
• Moderation actions (delete, mute, block) cannot be enforced server-side

Without backend support, any frontend chat implementation would be incomplete and unreliable.

---

Proposed solution

Core backend responsibilities

• Provide real-time message delivery to all participants in a room
• Persist a limited message history per room
• Enforce access control and moderation rules

Suggested implementation scope

• Define a RoomMessage data model with fields such as:
  • id
  • room_id
  • sender_id
  • content
  • timestamp
  • is_deleted
• Implement real-time message transport using:
  • WebSockets, or
  • existing real-time infrastructure already used by the backend
• Store the last N messages per room (e.g., 50–100)
• Load recent message history when a user joins a room

---

Moderation & security

Backend should enforce:

• Message deletion by room moderators
• Temporary chat mute at room level
• Blocking muted or banned users from sending messages
• Authorization checks to ensure only room participants can post messages

Moderation logic must be handled server-side, not only in the client.

---

Acceptance criteria

• Messages sent by one participant are delivered to all active room participants in real time
• Message history is retrievable when joining an ongoing room
• Moderation actions are enforced consistently
• System remains stable under concurrent room usage
• Backend APIs or socket events are documented

---

Impact

• Enables a critical missing feature in Resonate voice rooms
• Improves accessibility and engagement
• Provides a secure and scalable foundation for future features such as reactions, threads, and notifications
• Aligns with long-term roadmap and GSoC-sized contributions

---

References

• Related frontend issue: Add real-time text chat inside voice rooms with moderation support Resonate#730

[Muneerali199]

1. Architecture design

graph TD
    A[Client Applications] --> B[LiveKit WebSocket Server]
    B --> C[Chat WebSocket Handler]
    C --> D[Appwrite Database]
    C --> E[Message Moderation Service]
    
    subgraph "Frontend Layer"
        A
    end
    
    subgraph "Real-time Communication Layer"
        B
        C
    end
    
    subgraph "Data Layer"
        D
    end
    
    subgraph "Business Logic Layer"
        E
    end

Loading

2. Technology Description

• Backend Framework: Node.js with Express for REST APIs
• Real-time Communication: WebSocket using existing LiveKit infrastructure
• Database: Appwrite (PostgreSQL) for message persistence
• Authentication: Appwrite authentication with LiveKit token validation
• Message Queue: In-memory queuing for real-time delivery
• Environment: Serverless functions (Appwrite Functions)

3. Route definitions

Route	Purpose
/api/chat/history/:roomId	Retrieve message history for a specific room
/api/chat/delete/:messageId	Delete a message (moderator/admin only)
/api/chat/mute	Mute/unmute user from chat (moderator/admin only)
/api/chat/status/:roomId	Get chat status and user permissions

4. API definitions

4.1 Message Management APIs

Get Message History

GET /api/chat/history/:roomId

Query Parameters:

Param Name	Param Type	isRequired	Description
limit	number	false	Number of messages to retrieve (default: 50, max: 100)
before	string	false	Message ID to fetch messages before (for pagination)

Response:

Param Name	Param Type	Description
messages	array	Array of message objects
hasMore	boolean	Indicates if more messages are available

Example Response:

{
  "messages": [
    {
      "id": "msg_123",
      "roomId": "room_456",
      "senderId": "user_789",
      "senderName": "John Doe",
      "content": "Hello everyone!",
      "timestamp": "2024-01-19T10:30:00Z",
      "isDeleted": false
    }
  ],
  "hasMore": true
}

Delete Message

DELETE /api/chat/delete/:messageId

Headers:

Header Name	Header Type	isRequired	Description
Authorization	string	true	Bearer token with moderator/admin permissions

Response:

Param Name	Param Type	Description
success	boolean	Deletion status
message	string	Status message

4.2 WebSocket Events

Client to Server Events:

• chat:send - Send a new message
• chat:delete - Request message deletion (moderator only)
• chat:typing - Typing indicator

Server to Client Events:

• chat:message - New message broadcast
• chat:message_deleted - Message deletion notification
• chat:user_muted - User mute notification
• chat:error - Error notifications

5. Server architecture diagram

graph TD
    A[WebSocket Connection] --> B[Authentication Middleware]
    B --> C[Room Authorization]
    C --> D[Message Handler]
    D --> E[Moderation Service]
    D --> F[Database Service]
    E --> G[Message Validation]
    F --> H[Message Storage]
    
    subgraph "Request Processing"
        B
        C
        D
    end
    
    subgraph "Business Logic"
        E
        G
    end
    
    subgraph "Data Layer"
        F
        H
    end

Loading

6. Data model

6.1 Data model definition

erDiagram
    ROOM ||--o{ ROOM_MESSAGE : contains
    USER ||--o{ ROOM_MESSAGE : sends
    ROOM ||--o{ ROOM_PARTICIPANT : has
    USER ||--o{ ROOM_PARTICIPANT : participates
    ROOM_PARTICIPANT ||--o{ MODERATION_ACTION : performs
    
    ROOM {
        string id PK
        string name
        string adminId
        integer totalParticipants
        datetime createdAt
    }
    
    USER {
        string id PK
        string username
        string email
        boolean isBanned
    }
    
    ROOM_MESSAGE {
        string id PK
        string roomId FK
        string senderId FK
        string content
        datetime timestamp
        boolean isDeleted
        string deletedBy
        datetime deletedAt
    }
    
    ROOM_PARTICIPANT {
        string id PK
        string roomId FK
        string userId FK
        string role
        datetime joinedAt
        datetime leftAt
    }
    
    MODERATION_ACTION {
        string id PK
        string roomId FK
        string moderatorId FK
        string targetUserId FK
        string actionType
        string reason
        datetime actionTimestamp
        datetime expiresAt
    }

Loading

6.2 Data Definition Language

Room Messages Table (room_messages)

-- create table
CREATE TABLE room_messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    room_id VARCHAR(50) NOT NULL,
    sender_id VARCHAR(50) NOT NULL,
    sender_name VARCHAR(100) NOT NULL,
    content TEXT NOT NULL,
    timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    is_deleted BOOLEAN DEFAULT FALSE,
    deleted_by VARCHAR(50),
    deleted_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- create indexes
CREATE INDEX idx_room_messages_room_id ON room_messages(room_id);
CREATE INDEX idx_room_messages_sender_id ON room_messages(sender_id);
CREATE INDEX idx_room_messages_timestamp ON room_messages(timestamp DESC);
CREATE INDEX idx_room_messages_room_timestamp ON room_messages(room_id, timestamp DESC);

-- set up row-level security
ALTER TABLE room_messages ENABLE ROW LEVEL SECURITY;

-- create policies
CREATE POLICY "Room participants can view messages" ON room_messages
    FOR SELECT USING (
        room_id IN (
            SELECT room_id FROM room_participants 
            WHERE user_id = auth.uid() AND left_at IS NULL
        )
    );

CREATE POLICY "Authenticated users can insert messages" ON room_messages
    FOR INSERT WITH CHECK (
        auth.uid() = sender_id AND 
        room_id IN (
            SELECT room_id FROM room_participants 
            WHERE user_id = auth.uid() AND left_at IS NULL
        )
    );

CREATE POLICY "Room admins can delete messages" ON room_messages
    FOR UPDATE USING (
        room_id IN (
            SELECT room_id FROM rooms WHERE admin_id = auth.uid()
        )
    );

Moderation Actions Table (moderation_actions)

-- create table
CREATE TABLE moderation_actions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    room_id VARCHAR(50) NOT NULL,
    moderator_id VARCHAR(50) NOT NULL,
    target_user_id VARCHAR(50) NOT NULL,
    action_type VARCHAR(20) NOT NULL CHECK (action_type IN ('mute', 'unmute', 'delete_message')),
    reason TEXT,
    action_timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    expires_at TIMESTAMP WITH TIME ZONE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- create indexes
CREATE INDEX idx_moderation_actions_room_id ON moderation_actions(room_id);
CREATE INDEX idx_moderation_actions_target_user ON moderation_actions(target_user_id);
CREATE INDEX idx_moderation_actions_expires ON moderation_actions(expires_at) WHERE expires_at IS NOT NULL;

Grant permissions for Appwrite roles:

-- Grant basic read access to anon role
GRANT SELECT ON room_messages TO anon;
GRANT SELECT ON moderation_actions TO anon;

-- Grant full access to authenticated role
GRANT ALL PRIVILEGES ON room_messages TO authenticated;
GRANT ALL PRIVILEGES ON moderation_actions TO authenticated;

[KarthikChowdary07]

Hi @Muneerali199,

I’ve gone through the full issue description, architecture, and API definitions for the in-room text chat feature. This looks like a well-scoped backend feature and a great fit for a GSoC-sized contribution.

I’m currently setting up the Resonate backend locally and exploring the existing real-time infrastructure (LiveKit + Appwrite Functions). Before starting implementation, I wanted to confirm a couple of points:

1. Should LiveKit WebSocket be considered the primary real-time channel for chat events, or is Appwrite Realtime also an option?
2. Is message retention strictly limited to the last N messages per room, or should time-based cleanup also be considered?

If this aligns with the project direction, I’d like to start contributing incrementally (schema, APIs, and documentation first).

Thanks!