Chat Module

Core chat package for rooms, DMs, and real-time collaboration features.

Features

• Public lobby for all users
• Room-based chat with permission-gated creation
• Direct messages between users
• Real-time presence tracking
• Message history persistence
• Typing indicators
• File attachments
• WebRTC file sharing
• Collaborative documents
• Push notifications (iOS)
• Admin maintenance tools

What this package loads

From chat.doh.yaml:

• node modules: chat_server, chat_files_server, chat_push_server, chat_calls_server
• browser modules: chat_client, chat_files_client, chat_push_client, chat_calls_client
• shared collab modules: collab_docs, collab_richtext

Key files

• chat_server.js - socket handlers, REST routes, permission groups, room/member lifecycle
• chat_client.js - full chat UI (ChatApp, sidebar, messages, settings, overlays)
• chat_calls_server.js / chat_calls_client.js - room call signaling and call UI manager
• chat_push_server.js / chat_push_client.js - push subscription and notification integration
• chat.css and chat_calls.css - main visual styling

Permissions

User Permissions

chat_room_creator

• Assignable group
• Allows creating new chat rooms
• Permission: create:chat_room

log_viewer

• Assignable group
• Allows viewing server logs
• Permission: view:server_logs

chat_admin

• Assignable group
• Provides access to admin maintenance tools
• Permission: admin:chat_maintenance

Granting Permissions

# Grant room creation permission
doh users add-group username@example.com chat_room_creator

# Grant admin access
doh users add-group username@example.com chat_admin

# Grant both (add multiple groups)
doh users add-group username@example.com chat_room_creator
doh users add-group username@example.com chat_admin

# Or via interactive mode
doh users
# Then navigate to user management and add groups interactively

Admin Features

Users with the chat_admin permission group (or site_admin, admin, superadmin) have access to the Admin section in Settings.

Maintenance Tab

The Maintenance tab provides administrative tools for managing chat rooms:

Delete All Rooms

• Deletes all chat rooms except the lobby
• Removes all messages and room data permanently
• Requires double confirmation
• Endpoint: POST /api/chat/admin/delete-all-rooms

Delete Empty Rooms

• Deletes rooms with fewer than 3 messages
• Excludes the lobby from deletion
• Useful for cleaning up test or inactive rooms
• Returns count of deleted rooms
• Endpoint: POST /api/chat/admin/delete-empty-rooms

Both operations:

• Require authentication and admin permissions
• Cannot be undone
• Provide status feedback during operation
• Show deleted room counts on completion

Admin API Endpoints

Delete All Rooms

// Client
const res = await Doh.ajaxPromise('/api/chat/admin/delete-all-rooms', {});
// Response: { success: true, deleted_count: 5 }

Delete Empty Rooms

// Client
const res = await Doh.ajaxPromise('/api/chat/admin/delete-empty-rooms', {});
// Response: { success: true, deleted_count: 3 }

Both endpoints return:

• 401 if not authenticated
• 403 if user lacks admin:chat_maintenance permission
• 500 on server error
• 200 with { success: true, deleted_count: N } on success

Server capabilities

chat_server includes:

• guest identity flow via chat:set_guest_identity
• room join/leave/message/edit/delete socket operations
• typing, scroll sync, trace update/sync/delete/rename events for embed workflows
• browser-panel sync events (chat:browser_panel:*) for shared panel state
• room and DM HTTP APIs (/api/chat/*) for membership, contacts, invites, and settings
• page route /chat for authenticated full app view

It also exports a programmatic API (createSystemRoom, addMemberToRoom, removeMemberFromRoom, deleteRoom, plus helpers) for other modules to integrate with chat data.

Client architecture highlights

chat_client exposes a large composable UI surface. Notable patterns:

• ChatApp - root app controller with nickname/setup, room state, and sidebar wiring
• ChatMessageList / ChatMessage / ChatInput - core messaging pipeline
• ChatSidebar and related room/folder item patterns
• ChatSettings* panels (appearance, notifications, attachments, collab, links, connections)
• tiles and overlays for collab docs, logs, URLs, and browser panel content

chat_page bootstraps ChatApp for /chat.

Configuration

# pod.yaml
chat:
  lobby_name: "General Chat"
  max_message_length: 5000
  attachment_storage_enabled: true

Data model / Database tables

Primary idea tables in DB chat include:

• chat.rooms - Room metadata
• chat.room_members - Room membership
• chat.messages - Message history
• chat.trace - Debug/trace entries
• chat.connections - User connections
• chat.connection_requests - Pending connection requests
• chat.blocked_users - Blocked user list
• connection/contact/invite/sidebar layout tables managed by chat_server

See code in chat_server.js for full table constants and usage.

Local test

• Start server and open http://localhost:3000/chat
• Verify: room list load, DM creation, send/edit/delete message, typing indicator
• Verify socket-only flows: trace updates and browser panel sync in multiple clients