Chat

Core room-based chat system with DMs, presence tracking, AI bots, and real-time collaboration.

Overview

The chat module is the foundation of the doh_chat suite. It provides a full-featured chat application with public/private rooms, direct messages, real-time presence, file sharing, collaborative documents, AI bot conversations, and video/audio calls. The server handles all persistence (SQLite via AsyncDataforge), permission enforcement, and socket event routing. The client renders a composable UI with sidebar navigation, message lists, settings panels, and embedded content tiles.

Architecture

chat.doh.yaml
├── chat_url_utils          (shared)
├── ai_services             (nodejs)
├── chat_server             (nodejs)   ← routes, socket events, permissions, DB
├── chat_files_server       (nodejs)
├── chat_push_server        (nodejs)
├── chat_calls_server       (nodejs)
├── collab_docs             (shared)
├── collab_richtext         (shared)
├── user_avatar             (browser)
├── chat_client             (browser)  ← full UI (ChatApp + 40 patterns)
├── chat_files_client       (browser)
├── chat_push_client        (browser)
└── chat_calls_client       (browser)

Depends on: express_router, user_host (auth), db_dataforge Depended on by: chat_embed, issues

Features

• Public lobby room (always available, auto-join)
• Room-based chat with permission-gated creation
• Direct messages between users
• AI bot conversations with multi-provider support
• Real-time presence tracking (online/offline indicators)
• Message history with edit/delete and provenance tracking
• Typing indicators
• File attachments (via chat_files)
• WebRTC audio/video calls (via chat_calls)
• Collaborative code documents (via collab_docs)
• Collaborative rich text documents (via collab_richtext)
• Push notifications for iOS (via chat_push)
• Browser extension tool integration
• Contact/connection request system with blocking
• Sidebar folder organization with drag-and-drop
• Email invitations
• Server log streaming for admins
• YouTube video synchronization
• Scroll position synchronization
• Admin maintenance tools (delete rooms, token usage)

File Structure

Configuration

# pod.yaml
chat:
  lobby_name: "General Chat"
  max_message_length: 5000
  attachment_storage_enabled: true
  user_key_secret: "your-secret-key"  # AES key for encrypting user AI keys
  models: {}                          # AI model configuration overrides
  providers: {}                       # Provider key map overrides

Database Schema

All tables are in the chat database (SQLite via AsyncDataforge). All are Idea tables (id TEXT, data TEXT JSON blob) unless noted.

Constants: LOBBY_ID = 'lobby'

Permissions

Contexts

Groups

Granting Permissions

doh users add-group user@example.com chat_room_creator
doh users add-group user@example.com chat_admin

REST API Reference

All routes are prefixed with /api/chat/ unless noted. Auth = [Users.requireAuth]. Nickname = user must have set chat_name.

Profile & Settings

POST /api/chat/nickname

// Request
{ chat_name: string }  // 2-32 chars
// Response
{ success: true, chat_name, user: {...} }
// Errors: 400 (length), 409 (duplicate)

POST /api/chat/avatar

// Request
{ avatar_salt?: number, avatar_style?: string }
// Styles: 'initials', 'bottts-neutral', 'pixel-art', 'identicon', 'rings', 'shapes'
// Response
{ success: true, avatar_salt, avatar_style }

Rooms — Discovery

GET /api/chat/rooms/:id/messages

// Request (query/body)
{ limit?: number, skip?: number }
// Response
{ messages: [{ id, sender, sender_name, content, created_at, edited_at, deleted, provenance, ... }] }

Rooms — Management

POST /api/chat/rooms/create

// Request
{ name: string, members?: string[], type?: 'public'|'private'|'dm'|'bot'|'issue', is_public?: boolean }
// Response
{ room: { id, name, type, members, created_by, created_at, ... } }
// Broadcast: chat:room_updated to all members

Room Membership

POST /api/chat/rooms/:id/members

// Request
{ username: string, role?: 'member'|'admin' }
// Response
{ success: true, member: { username, role, joined_at, ... } }
// Broadcast: chat:member_added

Direct Messages

POST /api/chat/dm/:username

// Response
{ room: { id, type: 'dm', members: [user, target], partner_chat_name, ... } }
// Broadcast (if new): chat:room_created to both users

AI & Bots

GET /api/chat/ai/models

// Response
{
  models: [{
    nickname: string, name: string, description: string, provider: string,
    accessible: boolean, access_source: 'user_key'|'doh_pro'|null,
    reason: 'no_key'|null
  }],
  is_doh_pro: boolean
}

Bot Room Operations

Token Usage

GET /api/chat/token-usage

// Response
{
  models: { "model_name": { input_tokens, output_tokens, cost, calls } },
  total: { input_tokens, output_tokens, cost, calls }
}

Contacts & Connections

Blocking

Presence & Users

Sidebar & Links

Invites & Pro

Admin

// Response (both)
{ success: true, deleted_count: number }

Page Route

Socket Events Reference

All events use wrapSocketHandler for consistent error handling. Auth comes from socket.user (authenticated) or socket.guestUser (guest with nickname).

Connection & Identity

Room Lifecycle

Messaging

Message object shape (returned in chat:message callback and chat:message_received):

{
  id: string,                  // UUID
  room_id: string,
  sender: string,              // username
  sender_name: string,         // chat_name
  avatar_salt: number,
  avatar_style: string,
  content: string,
  created_at: number,          // timestamp
  edited_at: number | null,
  deleted: boolean,
  is_guest: boolean,
  original_sequence_number: number,
  adhoc_sequence_number: number | null,
  provenance: [{ action: 'created'|'edited'|'deleted', user, name, at }]
}

Typing

Presence

Embedded Documents

Browser Panels

Browser Tool Integration

See BROWSER_TOOLS.md for available tools.

Trace / Browser History

Scroll Sync

YouTube Sync

Server Logs

Calls (via chat_calls_server.js)

Push Notifications (via chat_push_server.js)

Room/Connection Broadcasts

Programmatic API

chat_server exports a Chat object for use by other modules:

Doh.Module('my_module', ['chat_server'], function(Chat) {
  // Create a system room
  const room = await Chat.createSystemRoom({
    name: 'Issue #42',
    type: 'issue',
    members: ['alice', 'bob'],
    adminUser: 'alice'
  });

  // Manage membership
  await Chat.addMemberToRoom(room.id, 'charlie', 'member');
  await Chat.removeMemberFromRoom(room.id, 'bob');

  // Query state
  const online = Chat.isUserOnline('alice');           // boolean
  const rooms = Chat.getUserRooms('alice');             // Room[]
  const msgs = Chat.getRecentMessages(room.id, 50);    // Message[]
  const isMember = Chat.isRoomMember(room.id, 'alice'); // boolean
  await Chat.deleteRoom(room.id);
});

Exported Functions

Client Patterns

Core UI (chat_client.js)

Content Tiles

Modals & Menus

Settings Panels

Sidebar Items

Utility

Call UI (chat_calls_client.js)

Key Design Patterns

Effective User Resolution

Socket handlers resolve user via: socket.user (authenticated) → socket.guestUser (guest) → null

Presence Tracking

onlineUsers Map: username → { sockets: Set<socket.id>, chat_name }
socketToUser Map: socket.id → username
userRooms Map: socket.id → Set<room_id>

Message Provenance

Every message tracks its edit/delete history:

provenance: [
  { action: 'created', user: 'alice', name: 'Alice', at: 1700000000 },
  { action: 'edited', user: 'alice', name: 'Alice', at: 1700000060 }
]

AI Key Encryption

User API keys are encrypted with AES-256-GCM. Stored as "iv:tag:encrypted" (hex, colon-separated). Masked display shows first 7 + last 4 characters.

Testing

1. Start server and open /chat
2. Verify: lobby loads, room list populates, nickname prompt appears on first visit
3. Verify messaging: send, edit, delete, typing indicator
4. Verify DMs: create DM, send messages, check unread badges
5. Verify calls: join call, audio/video toggle, screen share
6. Verify socket flows: trace updates, browser panel sync in multiple clients
7. Verify admin: delete empty rooms (requires chat_admin group)