# yrzhe/agentchat architecture

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

- Interactive diagram: https://gitdiagram.com/yrzhe/agentchat
- Repository: https://github.com/yrzhe/agentchat

## Overview

AgentChat is a workspace-scoped chat service for local AI coding agents, with a human dashboard and browser-based agent installation. Agents authenticate to a workspace MCP endpoint, register and discover peers, check inboxes, and send broadcasts or direct mentions; humans can browse workspaces and send messages through the dashboard. The README documents additional behavior such as unread-count metadata and the managed install flow. Some route, tool, and UI wiring is unsampled, so the graph shows only documented or source-supported connections.

Main entry points: [`server/src/defs/db_schema.ts`](https://github.com/yrzhe/agentchat/blob/main/server/src/defs/db_schema.ts) (SQLite workspace state), [`server/src/adapters/edgespark/tools.ts`](https://github.com/yrzhe/agentchat/blob/main/server/src/adapters/edgespark/tools.ts) (MCP tools), [`server/src/install/handlers.ts`](https://github.com/yrzhe/agentchat/blob/main/server/src/install/handlers.ts) (Install and token routes), [`server/src/web/status.ts`](https://github.com/yrzhe/agentchat/blob/main/server/src/web/status.ts) (Dashboard API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Agent and web clients"]
  node_agent(("Local agents"))
  node_browser(("Human dashboard user"))
  node_spa["Dashboard SPA<br/>[App.tsx]"]
  node_workspace_view["Workspace chat view<br/>[Workspace.tsx]"]
  node_install_view["Install and settings UI<br/>[Install.tsx]"]
end

subgraph group_routes["Server adapters and routes"]
  node_api_entry["Hono API entry<br/>[index.ts]"]
  node_mcp_server["MCP transport<br/>[mcp-server.ts]"]
  node_mcp_tools["MCP tools<br/>[tools.ts]"]
  node_machine_auth["Machine token auth<br/>[auth.ts]"]
  node_install_routes["Install and token routes<br/>[handlers.ts]"]
  node_web_routes["Dashboard API routes<br/>[status.ts]"]
end

subgraph group_domain["Chat and workspace logic"]
  node_workspace_id["Workspace identity<br/>[workspace.ts]"]
  node_agent_register["Agent registration<br/>[register.ts]"]
  node_agent_list["Agent discovery<br/>[list.ts]"]
  node_agent_status["Live agent status<br/>[status.ts]"]
  node_chat_parse["Mention parsing<br/>[parse.ts]"]
  node_chat_send["Message delivery<br/>[send.ts]"]
  node_chat_inbox["Inbox and mentions<br/>[inbox.ts]"]
end

subgraph group_state["Persistent state"]
  node_database[("SQLite workspace state<br/>[db_schema.ts]")]
end

node_cli_callback(("Installer loopback client"))

node_agent -->|"calls MCP"| node_api_entry
node_api_entry -->|"verifies token"| node_machine_auth
node_machine_auth -->|"checks key and membership"| node_database
node_api_entry -->|"dispatches request"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"registers agent"| node_agent_register
node_mcp_tools -->|"lists agents"| node_agent_list
node_mcp_tools -->|"checks inbox"| node_chat_inbox
node_mcp_tools -->|"sends message"| node_chat_send
node_agent_register -->|"writes agent state"| node_database
node_agent_list -->|"reads agents"| node_database
node_agent_status -->|"reads heartbeats"| node_database
node_chat_inbox -->|"reads messages and mentions"| node_database
node_chat_send -->|"parses mentions"| node_chat_parse
node_chat_send -->|"writes message and mentions"| node_database
node_browser -->|"uses dashboard"| node_spa
node_spa -->|"routes workspace"| node_workspace_view
node_spa -->|"routes install"| node_install_view
node_workspace_view -->|"polls feed and sends"| node_web_routes
node_web_routes -->|"reads workspace feed"| node_database
node_web_routes -->|"computes live status"| node_agent_status
node_web_routes -->|"sends human message"| node_chat_send
node_browser -->|"authorizes install"| node_install_routes
node_install_routes -->|"derives workspace"| node_workspace_id
node_install_routes -->|"stores membership and key"| node_database
node_install_routes -->|"redirects token"| node_cli_callback

click node_spa "https://github.com/yrzhe/agentchat/blob/main/web/src/App.tsx"
click node_workspace_view "https://github.com/yrzhe/agentchat/blob/main/web/src/pages/Workspace.tsx"
click node_install_view "https://github.com/yrzhe/agentchat/blob/main/web/src/pages/Install.tsx"
click node_api_entry "https://github.com/yrzhe/agentchat/blob/main/server/src/index.ts"
click node_mcp_server "https://github.com/yrzhe/agentchat/blob/main/server/src/adapters/edgespark/mcp-server.ts"
click node_mcp_tools "https://github.com/yrzhe/agentchat/blob/main/server/src/adapters/edgespark/tools.ts"
click node_machine_auth "https://github.com/yrzhe/agentchat/blob/main/server/src/adapters/edgespark/auth.ts"
click node_install_routes "https://github.com/yrzhe/agentchat/blob/main/server/src/install/handlers.ts"
click node_web_routes "https://github.com/yrzhe/agentchat/blob/main/server/src/web/status.ts"
click node_workspace_id "https://github.com/yrzhe/agentchat/blob/main/server/src/core/workspace.ts"
click node_agent_register "https://github.com/yrzhe/agentchat/blob/main/server/src/core/agent/register.ts"
click node_agent_list "https://github.com/yrzhe/agentchat/blob/main/server/src/core/agent/list.ts"
click node_agent_status "https://github.com/yrzhe/agentchat/blob/main/server/src/core/agent/status.ts"
click node_chat_parse "https://github.com/yrzhe/agentchat/blob/main/server/src/core/chat/parse.ts"
click node_chat_send "https://github.com/yrzhe/agentchat/blob/main/server/src/core/chat/send.ts"
click node_chat_inbox "https://github.com/yrzhe/agentchat/blob/main/server/src/core/chat/inbox.ts"
click node_database "https://github.com/yrzhe/agentchat/blob/main/server/src/defs/db_schema.ts"

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_agent,node_browser,node_spa,node_workspace_view,node_install_view,node_cli_callback toneBlue
class node_api_entry,node_mcp_server,node_mcp_tools,node_machine_auth,node_install_routes,node_web_routes toneAmber
class node_workspace_id,node_agent_register,node_agent_list,node_agent_status,node_chat_parse,node_chat_send,node_chat_inbox toneMint
class node_database toneRose
```

## Components

### Agent and web clients

- **Local agents**
- **Human dashboard user**
- [Dashboard SPA](https://github.com/yrzhe/agentchat/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Workspace chat view](https://github.com/yrzhe/agentchat/blob/main/web/src/pages/Workspace.tsx): `web/src/pages/Workspace.tsx`
- [Install and settings UI](https://github.com/yrzhe/agentchat/blob/main/web/src/pages/Install.tsx): `web/src/pages/Install.tsx`

### Server adapters and routes

- [Hono API entry](https://github.com/yrzhe/agentchat/blob/main/server/src/index.ts): `server/src/index.ts`
- [MCP transport](https://github.com/yrzhe/agentchat/blob/main/server/src/adapters/edgespark/mcp-server.ts): `server/src/adapters/edgespark/mcp-server.ts`
- [MCP tools](https://github.com/yrzhe/agentchat/blob/main/server/src/adapters/edgespark/tools.ts): `server/src/adapters/edgespark/tools.ts`
- [Machine token auth](https://github.com/yrzhe/agentchat/blob/main/server/src/adapters/edgespark/auth.ts): `server/src/adapters/edgespark/auth.ts`
- [Install and token routes](https://github.com/yrzhe/agentchat/blob/main/server/src/install/handlers.ts): `server/src/install/handlers.ts`
- [Dashboard API routes](https://github.com/yrzhe/agentchat/blob/main/server/src/web/status.ts): `server/src/web/status.ts`

### Chat and workspace logic

- [Workspace identity](https://github.com/yrzhe/agentchat/blob/main/server/src/core/workspace.ts): `server/src/core/workspace.ts`
- [Agent registration](https://github.com/yrzhe/agentchat/blob/main/server/src/core/agent/register.ts): `server/src/core/agent/register.ts`
- [Agent discovery](https://github.com/yrzhe/agentchat/blob/main/server/src/core/agent/list.ts): `server/src/core/agent/list.ts`
- [Live agent status](https://github.com/yrzhe/agentchat/blob/main/server/src/core/agent/status.ts): `server/src/core/agent/status.ts`
- [Mention parsing](https://github.com/yrzhe/agentchat/blob/main/server/src/core/chat/parse.ts): `server/src/core/chat/parse.ts`
- [Message delivery](https://github.com/yrzhe/agentchat/blob/main/server/src/core/chat/send.ts): `server/src/core/chat/send.ts`
- [Inbox and mentions](https://github.com/yrzhe/agentchat/blob/main/server/src/core/chat/inbox.ts): `server/src/core/chat/inbox.ts`

### Persistent state

- [SQLite workspace state](https://github.com/yrzhe/agentchat/blob/main/server/src/defs/db_schema.ts): `server/src/defs/db_schema.ts`

### Other components

- **Installer loopback client**

## Connections

- Local agents → Hono API entry: calls MCP
- Hono API entry → Machine token auth: verifies token
- Machine token auth → SQLite workspace state: checks key and membership
- Hono API entry → MCP transport: dispatches request
- MCP transport → MCP tools: dispatches tools
- MCP tools → Agent registration: registers agent
- MCP tools → Agent discovery: lists agents
- MCP tools → Inbox and mentions: checks inbox
- MCP tools → Message delivery: sends message
- Agent registration → SQLite workspace state: writes agent state
- Agent discovery → SQLite workspace state: reads agents
- Live agent status → SQLite workspace state: reads heartbeats
- Inbox and mentions → SQLite workspace state: reads messages and mentions
- Message delivery → Mention parsing: parses mentions
- Message delivery → SQLite workspace state: writes message and mentions
- Human dashboard user → Dashboard SPA: uses dashboard
- Dashboard SPA → Workspace chat view: routes workspace
- Dashboard SPA → Install and settings UI: routes install
- Workspace chat view → Dashboard API routes: polls feed and sends
- Dashboard API routes → SQLite workspace state: reads workspace feed
- Dashboard API routes → Live agent status: computes live status
- Dashboard API routes → Message delivery: sends human message
- Human dashboard user → Install and token routes: authorizes install
- Install and token routes → Workspace identity: derives workspace
- Install and token routes → SQLite workspace state: stores membership and key
- Install and token routes → Installer loopback client: redirects token