# blackbeaneagles/zerocomet architecture

> Architecture diagram of the GitHub repository blackbeaneagles/zerocomet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blackbeaneagles/zerocomet
- Repository: https://github.com/blackbeaneagles/zerocomet

## Overview

Agent Pager turns an allowlisted group-chat request into a workspace edit, test run, and result card; a teammate can then ship or undo the changes. The browser provides chat, live status, result cards, and a console, while the server mints login tokens and coordinates CometChat with the agent runner. The README documents callback delivery and preview alongside polling. The source excerpts and index support the main calls; some browser transport details and unsampled implementation are documented but not shown directly.

Main entry points: [`web/src/components/Room.jsx`](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Room.jsx) (Chat room), [`server/index.js`](https://github.com/blackbeaneagles/zerocomet/blob/main/server/index.js) (HTTP server), [`server/brain.js`](https://github.com/blackbeaneagles/zerocomet/blob/main/server/brain.js) (Message coordinator), [`web/src/components/Messages.jsx`](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Messages.jsx) (Messages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Chat interface"]
  node_app["App shell<br/>[App.jsx]"]
  node_login["Login<br/>[Login.jsx]"]
  node_room["Chat room<br/>[Room.jsx]"]
  node_messages["Messages<br/>[Messages.jsx]"]
  node_cards["Result cards<br/>[Cards.jsx]"]
  node_composer["Message composer<br/>[Composer.jsx]"]
  node_console["Agent console<br/>[Console.jsx]"]
  node_avatars["Avatars<br/>[Avatar.jsx]"]
  node_chatlib["Chat transport<br/>[chat.js]"]
  node_commands["Command parser<br/>[commands.js]"]
  node_mock["Demo agent<br/>[mock.js]"]
end

subgraph group_server["Pager server"]
  node_server["HTTP server<br/>[index.js]"]
  node_config["Runtime config<br/>[config.js]"]
  node_brain["Message coordinator<br/>[brain.js]"]
  node_cometchat["CometChat REST client<br/>[cometchat.js]"]
end

subgraph group_agent["Agent workflow"]
  node_runner["Agent runner<br/>[agent.js]"]
end

subgraph group_workspace["Editable workspace"]
  node_workspace["Launchpad workspace"]
  node_git[("Workspace history")]
end

node_human(("Group members"))
node_chatservice{{"CometChat"}}
node_claude{{"Claude Code"}}

node_human -->|"sends messages"| node_chatservice
node_chatservice -.->|"delivers callback"| node_server
node_server -->|"routes messages"| node_brain
node_server -->|"reads settings"| node_config
node_server -->|"mints tokens"| node_cometchat
node_server -->|"starts polling"| node_brain
node_brain -->|"checks allowlist"| node_config
node_brain -->|"reads and posts"| node_cometchat
node_brain -->|"runs or ships"| node_runner
node_cometchat -->|"uses REST API"| node_chatservice
node_runner -->|"runs prompt"| node_claude
node_runner -->|"edits and tests"| node_workspace
node_runner -->|"diffs and commits"| node_git
node_workspace -->|"stores history"| node_git
node_app -->|"renders"| node_login
node_app -->|"renders"| node_room
node_login -.->|"authenticates"| node_chatlib
node_login -->|"requests token"| node_server
node_room -->|"uses transport"| node_chatlib
node_room -->|"uses in demo"| node_mock
node_room -->|"renders"| node_messages
node_room -->|"renders"| node_composer
node_room -->|"renders"| node_console
node_messages -->|"renders"| node_cards
node_messages -->|"uses step icons"| node_console
node_messages -->|"renders"| node_avatars
node_console -->|"renders"| node_avatars
node_composer -->|"parses commands"| node_commands
node_chatlib -->|"uses JS SDK"| node_chatservice
node_chatservice -->|"delivers chat cards"| node_human

click node_app "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/App.jsx"
click node_login "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Login.jsx"
click node_room "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Room.jsx"
click node_messages "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Messages.jsx"
click node_cards "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Cards.jsx"
click node_composer "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Composer.jsx"
click node_console "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Console.jsx"
click node_avatars "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Avatar.jsx"
click node_chatlib "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/lib/chat.js"
click node_commands "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/lib/commands.js"
click node_mock "https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/lib/mock.js"
click node_server "https://github.com/blackbeaneagles/zerocomet/blob/main/server/index.js"
click node_config "https://github.com/blackbeaneagles/zerocomet/blob/main/server/config.js"
click node_brain "https://github.com/blackbeaneagles/zerocomet/blob/main/server/brain.js"
click node_cometchat "https://github.com/blackbeaneagles/zerocomet/blob/main/server/cometchat.js"
click node_runner "https://github.com/blackbeaneagles/zerocomet/blob/main/server/agent.js"
click node_workspace "https://github.com/blackbeaneagles/zerocomet/tree/main/workspace"
click node_git "https://github.com/blackbeaneagles/zerocomet/tree/main/workspace"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_login,node_room,node_messages,node_cards,node_composer,node_console,node_avatars,node_chatlib,node_commands,node_mock toneBlue
class node_server,node_config,node_brain,node_cometchat toneAmber
class node_runner toneMint
class node_workspace,node_git toneRose
class node_human,node_chatservice,node_claude toneIndigo
```

## Components

### Chat interface

- [App shell](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Login](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Login.jsx): `web/src/components/Login.jsx`
- [Chat room](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Room.jsx): `web/src/components/Room.jsx`
- [Messages](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Messages.jsx): `web/src/components/Messages.jsx`
- [Result cards](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Cards.jsx): `web/src/components/Cards.jsx`
- [Message composer](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Composer.jsx): `web/src/components/Composer.jsx`
- [Agent console](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Console.jsx): `web/src/components/Console.jsx`
- [Avatars](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/components/Avatar.jsx): `web/src/components/Avatar.jsx`
- [Chat transport](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/lib/chat.js): `web/src/lib/chat.js`
- [Command parser](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/lib/commands.js): `web/src/lib/commands.js`
- [Demo agent](https://github.com/blackbeaneagles/zerocomet/blob/main/web/src/lib/mock.js): `web/src/lib/mock.js`

### Pager server

- [HTTP server](https://github.com/blackbeaneagles/zerocomet/blob/main/server/index.js): `server/index.js`
- [Runtime config](https://github.com/blackbeaneagles/zerocomet/blob/main/server/config.js): `server/config.js`
- [Message coordinator](https://github.com/blackbeaneagles/zerocomet/blob/main/server/brain.js): `server/brain.js`
- [CometChat REST client](https://github.com/blackbeaneagles/zerocomet/blob/main/server/cometchat.js): `server/cometchat.js`

### Agent workflow

- [Agent runner](https://github.com/blackbeaneagles/zerocomet/blob/main/server/agent.js): `server/agent.js`

### Editable workspace

- [Launchpad workspace](https://github.com/blackbeaneagles/zerocomet/tree/main/workspace): `workspace`
- [Workspace history](https://github.com/blackbeaneagles/zerocomet/tree/main/workspace): `workspace`

### Other components

- **Group members**
- **CometChat**
- **Claude Code**

## Connections

- Group members → CometChat: sends messages (evidence: `README.md`)
- CometChat → HTTP server: delivers callback (evidence: `README.md`)
- HTTP server → Message coordinator: routes messages (evidence: `server/index.js`)
- HTTP server → Runtime config: reads settings (evidence: `server/index.js`)
- HTTP server → CometChat REST client: mints tokens (evidence: `server/index.js`)
- HTTP server → Message coordinator: starts polling (evidence: `server/index.js`)
- Message coordinator → Runtime config: checks allowlist (evidence: `server/brain.js`)
- Message coordinator → CometChat REST client: reads and posts (evidence: `server/brain.js`)
- Message coordinator → Agent runner: runs or ships (evidence: `server/brain.js`)
- CometChat REST client → CometChat: uses REST API (evidence: `server/cometchat.js`)
- Agent runner → Claude Code: runs prompt (evidence: `server/agent.js`)
- Agent runner → Launchpad workspace: edits and tests (evidence: `README.md`)
- Agent runner → Workspace history: diffs and commits (evidence: `server/agent.js`)
- Launchpad workspace → Workspace history: stores history
- App shell → Login: renders (evidence: `web/src/App.jsx`)
- App shell → Chat room: renders (evidence: `web/src/App.jsx`)
- Login → Chat transport: authenticates (evidence: `README.md`)
- Login → HTTP server: requests token (evidence: `README.md`)
- Chat room → Chat transport: uses transport (evidence: `web/src/components/Room.jsx`)
- Chat room → Demo agent: uses in demo (evidence: `web/src/components/Room.jsx`)
- Chat room → Messages: renders (evidence: `web/src/components/Room.jsx`)
- Chat room → Message composer: renders (evidence: `web/src/components/Room.jsx`)
- Chat room → Agent console: renders (evidence: `web/src/components/Room.jsx`)
- Messages → Result cards: renders (evidence: `web/src/components/Messages.jsx`)
- Messages → Agent console: uses step icons (evidence: `web/src/components/Messages.jsx`)
- Messages → Avatars: renders (evidence: `web/src/components/Messages.jsx`)
- Agent console → Avatars: renders (evidence: `web/src/components/Console.jsx`)
- Message composer → Command parser: parses commands (evidence: `web/src/components/Composer.jsx`)
- Chat transport → CometChat: uses JS SDK (evidence: `README.md`)
- CometChat → Group members: delivers chat cards (evidence: `README.md`)
