doh_chat

Real-time chat, collaboration, and AI services suite for Doh.js applications.

Suite Overview

doh_chat is a full-featured communication platform built on Doh.js. It provides room-based chat with direct messages, peer-to-peer file sharing, real-time collaborative document editing (code and rich text), multi-provider AI integration, issue tracking, and embeddable chat widgets. All modules share a common Socket.IO transport layer and permission system.

Suite Architecture

                              ┌─────────────────┐
                              │      chat        │  Core chat system
                              │  rooms, DMs,     │  (server + browser)
                              │  presence, bots  │
                              └────────┬─────────┘
                                       │ loads
     ┌───────────┬────────────┬────────┼──────────┬────────────┬────────────┐
     │           │            │        │           │            │            │
  ┌──┴────┐ ┌───┴───┐ ┌──────┴──┐ ┌──┴──────┐ ┌──┴──────┐ ┌──┴──────┐ ┌──┴──────────┐
  │chat_  │ │chat_  │ │chat_    │ │chat_    │ │chat_    │ │chat_    │ │ ai_services │
  │files  │ │url_   │ │push_    │ │web_push │ │calls    │ │onboarding│ │ AI gateway  │
  │WebRTC │ │utils  │ │server   │ │(VAPID/  │ │WebRTC   │ │spotlight │ │ (6 providers│
  │file   │ │       │ │(APNs/   │ │Web Push)│ │activities│ │tour      │ │ + token     │
  │xfer   │ │       │ │iOS push)│ │         │ │         │ │          │ │ tracking)   │
  └───────┘ └───────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────┬──────┘
                                                                               │
  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                    ┌──────┴──────┐
  │ collab_docs  │ │  collab_     │ │  collab_     │                    │ ai_keys_    │
  │ Monaco code  │ │  richtext    │ │  tracker     │                    │ admin       │
  │ editor + Yjs │ │ TinyMCE+Yjs │ │ task list+Yjs│                    │ key mgmt UI │
  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘                    └─────────────┘
         │                │                │
         └────────┬───────┴────────────────┘
           ┌──────┴──────┐
           │collab_shared│
           │ Yjs socket  │
           │ provider    │
           └─────────────┘

  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  │ chat_proxy  │ │   dohtop    │ │   games     │ │chat_io_     │ │ chat_       │
  │ URL proxy   │ │ floating    │ │ in-room     │ │devices      │ │ extensions  │
  │ for embeds  │ │ window sys  │ │ multiplayer │ │ mic/cam/    │ │ Chrome MV3  │
  │ (htmlpog)   │ │ tab groups  │ │ game engine │ │ speaker mgmt│ │ + Safari    │
  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘

  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  │ chat_embed  │ │    chat_    │ │   issues    │ │ user_avatar │
  │ iframe chat │ │  messenger  │ │ bug capture │ │ DiceBear    │
  │ for embeds  │ │ floating bar│ │ + tracking  │ │ avatars     │
  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘

  ┌─────────────┐ ┌─────────────┐
  │ dohpro_     │ │ dohpro_     │
  │ admin       │ │ sales       │
  │ tier/credit │ │ /pro pricing│
  │ management  │ │ /what-is-   │
  │ /admin/     │ │ dohchat     │
  │ dohpro      │ │ pages       │
  └─────────────┘ └─────────────┘

Module Dependency Tree

chat.doh.js
├── chat_url_utils              (shared)
├── ai_services                 (nodejs, async)
├── chat_server                 (nodejs)   ← routes, socket events, permissions, DB
├── chat_files_server           (nodejs)
├── chat_push_server            (nodejs)   ← APNs push (iOS/macOS)
├── chat_web_push_server        (nodejs)   ← VAPID Web Push (browsers)
├── chat_calls_server           (nodejs)   ← Activities (WebRTC signaling)
├── chat_proxy_server           (nodejs)   ← URL proxy for embeds (htmlpog)
├── games                       (shared, async)
├── collab_docs                 (shared, async)
├── collab_richtext             (shared, async)
├── collab_tracker              (shared, async)  ← collaborative task list (Yjs CRDT)
├── dohtop                      (await)    ← floating window system
├── user_avatar                 (browser)
├── chat_client                 (browser, await)  ← full UI (ChatApp + 60+ patterns)
├── chat_files_client           (browser, async)
├── chat_push_client            (browser, async)
├── chat_web_push_client        (browser, async)
├── chat_calls_client           (browser, async)  ← Activities UI
├── chat_onboarding_client      (browser, async)
└── chat_io_devices_client      (browser, async)  ← I/O device management

Dependency flow: chat is the core — it loads chat_files, chat_push_server, chat_web_push_server, chat_calls, chat_proxy_server, chat_onboarding_client, chat_io_devices_client, ai_services, collab_docs, collab_richtext, collab_tracker, games, dohtop, and user_avatar. Standalone packages like chat_embed, issues, dohpro_admin, and dohpro_sales depend on chat. The chat_messenger is browser-only and used by chat_embed and issues for floating UI.

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

Module Inventory

How Modules Load

1. Add chat (or chat_embed, issues, etc.) to host_load in boot.pod.yaml
2. The chat.doh.js package declares the dependency graph
3. Sub-packages like chat_embed, issues, dohpro_admin, and dohpro_sales list chat as a dependency and add their own server/client modules

# boot.pod.yaml
host_load:
  - express_router
  - users
  - chat           # Loads the full chat stack
  - chat_embed     # Optional: adds embed endpoints
  - issues         # Optional: adds issue tracking
  - ai_keys_admin  # Optional: adds key management UI
  - dohpro_admin   # Optional: adds /admin/dohpro tier management
  - dohpro_sales   # Optional: adds /pro and /what-is-dohchat pages

Prerequisites

• Doh.js runtime
• users module (provides authentication, Users.requireAuth, Doh.permit())
• express_router module (provides Router.AddRoute, Router.SendJSON, Router.SendHTML)

Quick Start

With the local server running:

Supplementary Documentation

• BROWSER_TOOLS.md — Browser extension tool registry for bot interactions
• PUSH_NOTIFICATIONS.md — APNs + Web Push notification systems
• TURN_SERVER_SETUP.md — COTURN server setup for WebRTC
• STATUS_LOCATIONS.md — Presence status display across 9 UI locations
• AI_SERVICES_DOCUMENTATION.md — Detailed AI provider/model reference with pricing
• chat-url-tile-layout.md — URL tile DOM structure and resize mechanics

Chat Module Overview

Configuration & Database

Pod 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'

Room ownership: Rooms have an owners array (string[]) that controls who can delete or clear the room. Regular rooms are created with owners: [creator]. DM rooms are created with owners: [userA, userB] (both participants). Old rooms without an owners field fall back to created_by for permission checks. DM rooms cannot be deleted or cleared regardless of ownership.

Permissions

Contexts

Groups

Granting Permissions

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

Features

Messaging

Core send/edit/delete with emoji reactions. Messages carry provenance tracking (who created, edited, or deleted, with timestamps). Sticky notes via chat:notey_edit for the notey room format. Message reordering via chat:reorder. Unread counts tracked per-user per-room.

Message object shape:

{
  id: string,                  // UUID
  room_id: string,
  sender: string,              // username (or 'system' for system messages, 'bot:<id>' for bots)
  sender_name: string,         // chat_name (system messages only; regular messages resolve from ChatUserStore)
  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 }]
}

Rooms & Formats

Public lobby room (always available, auto-join). Permission-gated room creation. Room types: public, private, dm, bot, issue. Room format switching between:

• chatty — standard linear chat
• notey — sticky note grid with inline editing
• jelly — spatial canvas with draggable message tiles and connections
• gamey — game interface format

Room export/import via YAML. Activity rollup folds consecutive system messages into collapsible summaries.

Direct Messages

Create/get DM rooms via POST /api/chat/dm/:username or POST /api/chat/dm/bot/:bot_id. DM rooms have both participants as co-owners and cannot be deleted or cleared. Bot DMs auto-create a bot room with the specified bot.

Presence & Typing

Rich presence tracking: Online / Away / Busy / Offline with per-user persistence. Status saved to user record and broadcast to all lobby users via chat:presence. Typing indicators broadcast per-room excluding the sender.

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

status is loaded from Users.getUserByUsername() on connect (field chat_status, defaults to 'online'). Updated in-memory on POST /api/chat/status and re-saved via Users.updateUser(). On socket disconnect the broadcast uses status: 'offline' regardless of saved value.

AI Bots

Multi-provider AI support (Anthropic, OpenAI, Google, xAI, Moonshot, HuggingFace) via ai_services. Users create custom bots with system prompts and model selection. Bot DM rooms for private conversations. User API keys encrypted with AES-256-GCM, stored as "iv:tag:encrypted" (hex, colon-separated). Masked display shows first 7 + last 4 characters.

Bot tool indicators (chat:bot_tool_use / chat:bot_tool_done) show real-time tool usage. Bot chaining (chat:bot_chain) allows bots to hand off to other bots. Browser extension tool integration lets bots interact with the user's browser — see BROWSER_TOOLS.md.

Workflow Execution

Bots execute via a graph-based workflow engine (agent_executor) instead of flat generateBotResponse. When a bot has a valid workflow document (a Yjs surface canvas with at least one input node and one output node), the graph executes; otherwise the bot falls back to flat mode (direct generateBotResponse).

• agent_executor — walks the workflow graph: finds the input node, resolves edges to downstream nodes, executes each node type via agent_node_types, and routes results along edges until reaching the output node.
• handleBotResponseOutput — shared post-response handler used by both the workflow path and the flat path. Saves the bot's message, broadcasts it to the room, fires notifications, and handles bot-to-bot delegation (chaining).
• ChatBotContext — SPR source declaration (= {}) that shares helpers (DB access, bot lookup, message formatting) between chat_server, agent_executor, and agent_node_types without requiring load chain dependencies between them.
• workflowFromLegacy — validates and rebuilds workflow documents that are missing or incomplete. Called by the ensure-workflow endpoint. Checks for input/output nodes and re-creates them if absent.

Workflow Socket Events

Stuck Queue Protection

Bot response processing sets a processing flag to prevent duplicate concurrent executions. A 2-minute auto-reset timer clears the flag if the bot becomes stuck (crash, timeout, unhandled error), allowing the next queued message to proceed.

Approval & Scheduling

AI bots can request approval before executing high-impact actions.

Flow:

1. Bot generates an [APPROVAL] message with a JSON card describing the proposed action
2. Room owner responds via chat:approval_respond
3. On approval, if the payload indicates a scheduled_task, the server creates a task record with schedule type and next-run timestamp
4. A scheduler loop (SCHEDULER_INTERVAL_MS) polls for due tasks and queues bot responses
5. chat:approval_resolved broadcast updates the card UI to approved or denied

Scheduled tasks support once and recurring types with configurable intervals. Tasks can be cancelled or reactivated via REST API.

Context Compression

Bot room conversations can be compressed or fully cleared to manage AI context window size.

• Clear context (POST /api/chat/rooms/:id/clear-context) — hard deletes all messages, wipes summary, sets last_cleared_at. Owner only.
• Compress (POST /api/chat/rooms/:id/compress) — uses the room's AI model to summarize the conversation, replaces all messages with a summary system message. Owner only.
• Admin clear (POST /api/chat/admin/clear-room) — hard deletes all messages in any room. Requires admin:chat_maintenance.

Connections, Contacts & Blocking

Connections are bidirectional friendship links. Send/accept/decline requests. If mutual pending requests exist, auto-accepts. On connection, the server auto-creates a DM room and sends chat:navigate_to_room to switch to it. Connection records use compound ID "user1:user2" (alphabetically sorted) for deduplication.

Contacts are a lightweight one-way list for quick access. Add/remove via REST.

Blocking prevents message visibility and connection requests. Block records checked server-side in filterBlockedMessages before returning message history. Blocking cancels any pending connection requests between the users. The onlineUsers lobby list also filters blocked users per requesting user.

Notifications

In-app notification bell with toast popups, unread badges, and per-user scope preferences. Paginated notification list with mark-read and clear-all. Socket events chat:notification and chat:notification_updated for real-time delivery.

Push notifications via two channels:

• APNs (iOS/macOS) via chat_push_server — see PUSH_NOTIFICATIONS.md
• Web Push (browsers) via chat_web_push_server using VAPID keys. Service worker chat-notification-sw.js handles display and click-to-open navigation.

Activities

Activities (WebRTC audio/video/screen sharing) are managed by chat_calls_server.js. Fully mesh topology — every participant establishes a direct peer connection to every other. The server acts as a signaling relay only.

Participant A ──── direct RTCPeerConnection ──── Participant B
      │                                                │
      └────── direct RTCPeerConnection ──── Participant C

Multi-device support: When a user joins from a second socket, the join mode controls behavior: 'move' (default) tears down old sockets and emits chat:call:replaced; 'add' keeps existing sockets and adds the new one, enabling multi-device participation (e.g. phone mic + laptop screen). chat:call:check_existing lets the client detect an active session before choosing a mode.

TURN credentials: Generated per-request using HMAC-SHA1. The /api/chat/calls/ice endpoint returns a fresh ice_servers array with time-limited TURN entries.

Pod configuration:

max_participants is sent to the browser via browser_pod. turn_secret and turn_host remain server-side only. See TURN_SERVER_SETUP.md for COTURN setup.

Jelly Canvas

Messages in jelly format have persistent x, y, width, height positions stored under _jelly. Position updates via chat:jelly_positions, broadcast to room members.

Room merge (chat:room_merge) groups selected messages into a new private sub-room with parent_room_id pointing back. Posts a system message in the parent as a room-tile marker. Returns an undo descriptor for reversal.

Undo (chat:room_merge_undo) restores deleted messages, removes the system tile, and deletes the sub-room.

Add message (chat:room_add_message) moves or copies a single message into an existing sub-room with optional jelly positioning.

Connections (chat:jelly_connections) allow add/remove of visual connections between jelly messages.

Collaboration

Embedded collaborative documents (Monaco code editor, TinyMCE rich text) and collaborative task tracking via Yjs CRDT sync. Document tile size and open state synced across room members via chat:update_doc_size and chat:update_doc_open_state.

Shared browser panels (chat:browser_panel:*) for collaborative URL browsing within a room — open, navigate, move/resize, and close panels synced to all members.

URL Trace

The chat_embed browser extension reports page visits to a chat room. Each visit creates or updates a trace entry keyed by room_id:urlKey (hostname + pathname). A system message is posted with trace: true flag. Trace entries include URL, title, favicon, visitor info, scroll anchor, and user-assigned nickname.

Scroll & YouTube Sync

Scroll sync relays scroll position within a shared browsing context via chat:scroll_sync. Used by chat_embed to synchronize the host page scroll position with room participants.

YouTube sync relays player state (play/pause/seek with timestamp) across room members via chat:yt_sync so everyone watches in sync.

Server Log Streaming

Users with the log_viewer group can subscribe to real-time server log entries via chat:logs:subscribe. Entries stream as chat:logs:entry with timestamp, level, message, and source. Subscription is per-socket, auto-cleaned on disconnect.

Games

In-room multiplayer games via the gamey room format. Game engine handles start/end/move/state lifecycle. Available games: Hangman, Twenty Questions, Poker, WOPR, Exquisite Corpse. See ../games/README.md for game definitions and engine API.

REST API Reference

All routes prefixed /api/chat/ unless noted. Doh routes infer GET (no data) or POST (data sent) from the request. Auth = [Users.requireAuth]. Nickname = user must have set chat_name.

Profile & Settings

Rooms

Direct Messages

AI & Bots

Token Usage

Connections & Contacts

Notifications & Invites

Approval & Scheduling

Presence & Users

Sidebar & Links

Pro & Misc

Activities

Push Notifications

Admin

Page Routes

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

Typing & Presence

Jelly Canvas

Collaboration & Sync

Browser Panels & Tools

URL Trace

Bots & Approvals

Activities

Notifications & Push

Games

Server Logs

Connections & Social

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

Activities UI (chat_calls_client.js)

Architecture Notes

Unified Socket Architecture

All real-time features share a single Doh.socket connection. The client uses two composable patterns:

ChatAppSocket — a mixin pattern (no parent, non-html) that handles app-level socket events shared across all chat surfaces. Defines melded Method hooks (onPresenceChanged, onRoomCreated, onRoomUpdated, onRoomInvite, onRoomDeleted, onMemberRemoved, onUnreadUpdate, onSidebarLayout, onNotification, onNotificationUpdated) with base implementations that update centralized stores. Wired via wireAppSocket().

ChatConversation — a shared html base for per-conversation UI (messages, input, typing, controls). Both ChatApp (full page) and ChatMessengerPopup (floating window) extend it. Provides setupCoreSocketListeners() for message CRUD, layout sync, reactions, games, and format changes. Also provides setupCoreTypingListeners() for typing indicators.

Composition: ChatApp inherits both — Pattern('ChatApp', ['ChatConversation', 'ChatAppSocket'], {...}). ChatMessengerBar separately calls wireAppSocket() for app-level events, while each ChatMessengerPopup extends ChatConversation for its own conversation scope.

Client Stores

Four singleton stores provide reactive data across all chat surfaces:

• ChatUserStore — user display data cache (chat_name, avatar_salt, avatar_style). Messages only carry sender (username); display data resolves from this store at render time. Methods: update(), get(), subscribe(), renderAvatar(), seedFromRooms(), seedFromSenders().

• ChatPresenceStore — online/away/busy/offline status per user. On reconnect, all cached users reset to offline before re-seeding. Methods: update(), get() (defaults to 'offline'), subscribe().

• RoomActivityStore — live activities per room (activities, games, open windows). Tracks participant counts, voice/video/screen flags, active games, and local activity state. Methods: update(), get(), seed(), setLocalCall(), setOpen(), subscribe(), _fromCallSummary().

• ChatRoomStore — centralized room object cache. Lazy-fetches from /api/chat/rooms on first ensure(), dedupes concurrent calls, and auto-seeds ChatUserStore for DM partner data. Kept live by socket events (chat:room_created → update(), chat:room_updated → update(), chat:room_deleted → remove()). Bulk-seeded by ChatApp.loadRooms() and ChatSidebar messenger mode via seed() to avoid redundant fetches. Methods: ensure(), get(roomId), getAll(), update(room), remove(roomId), seed(rooms), subscribe(fn).

• CollabDocStore — centralized collab document metadata cache (id, title, type, owner, language, updated_at). SPR source declaration (= {}) on Doh.Globals.CollabDocStore for cross-module access. Lazy-fetches from /api/collab/docs/:id on ensure(docId) (deduped). Kept live by collab:doc:meta_updated socket events wired in wireAppSocket(). Surfaces and trackers emit collab:doc:update_meta when their Yjs name changes, which triggers the server broadcast and store update. ChatCollabTile subscribes for live title updates and calls ensure() on mount to refresh stale message-time titles. Methods: ensure(docId), get(docId), update(doc), subscribe(fn).

Files DohtopWindow

The Files browser runs as a DohtopWindow (FilesDohtopContent pattern) with a room-navigation sidebar and a ChatRoomFileViewer panel.

Multi-instance: Multiple Files windows can be open simultaneously. Default click on the Files button opens/restores the singleton 'files' window. Right-click opens the dock context menu of the last-interacted Files window (which includes "New Files Window"). Each window has independent filter state, room selection, view mode, and sidebar width — persisted via per-window localStorage keys (chat-files-<windowId>-*).

Dynamic title: The window title and dock item label reflect the active type filters — e.g. "Files + Docs + Links", "Docs", "Files + Links". Updates on every filter change.

Room sidebar grouping: Rooms are partitioned into three sections:

1. Regular rooms — displayed with format icons (chatty/notey/jelly/gamey), DM avatars via ChatUserStore, bot gear icons, lobby #
2. Issues folder — collapsible, starts collapsed, expanding auto-selects all issue files
3. Deleted Rooms folder — collapsible, starts collapsed, shows orphaned files from destroyed rooms

Filter toggle behavior: Type filters (Files/Docs/Links) and storage filters use click-to-solo, Ctrl/Shift-click-to-toggle. Tooltips show "Hold Ctrl to select multiple". Same toggle pattern for room selection in the sidebar.

Room context menu: Right-click a room in the files sidebar for "Open Room" (navigates in ChatApp) and "Open in New Window".

Orphaned files: The server (/api/chat/files/user) returns files uploaded by the current user whose room was deleted, enriched with room_type: 'deleted' and room_deleted: true. The /api/chat/links/user and /api/chat/collabs/user endpoints similarly return orphaned links/collabs.

Effective User Resolution

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

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 }
]

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 activities: join activity, 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)