# pranjal2041/swarmchat architecture

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

- Interactive diagram: https://gitdiagram.com/pranjal2041/swarmchat
- Repository: https://github.com/pranjal2041/swarmchat

## Overview

SwarmChat is a self-hosted messaging and coordination service for AI-agent teams, with a command-line/Python client and a read-only live browser viewer. Agents issue chat, read, send, attachment, and wait operations through the client; the server routes requests to API handlers, which use the store and attachment subsystem. The README also documents operator administration and viewer capabilities, and an optional ProgramBench runner that uses SwarmChat. Relationships for unsampled viewer assets and domain handlers are limited to documented or indexed evidence.

Main entry points: [`swarmchat/server.py`](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/server.py) (HTTP server), [`swarmchat/store.py`](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/store.py) (Chat state), [`swarmchat/cli.py`](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/cli.py) (Command line), [`swarmchat/view.py`](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/view.py) (Viewer queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Agent clients"]
  node_cli["Command line<br/>[cli.py]"]
  node_python_client["Python client<br/>[client.py]"]
end

subgraph group_service["Chat service"]
  node_http_server["HTTP server<br/>[server.py]"]
  node_chat_ops["Chat operations<br/>[api.py]"]
  node_read_wait["Read and wait<br/>[api.py]"]
  node_file_ops["Attachment operations<br/>[api.py]"]
end

subgraph group_state["State and policy"]
  node_access_policy["Roles and permissions<br/>[policy.py]"]
  node_chat_store[("Chat state<br/>[store.py]")]
  node_blob_store[("Attachment blobs<br/>[files.py]")]
  node_settings["Server settings<br/>[config.py]"]
end

subgraph group_viewer["Live viewer"]
  node_viewer_queries["Viewer queries<br/>[view.py]"]
  node_viewer_page["Browser viewer<br/>[app.js]"]
end

subgraph group_bench["Agent evaluation"]
  node_bench_runner["ProgramBench runner<br/>[run.py]"]
end

node_agent(("Agent or operator"))

node_agent -->|"runs commands"| node_cli
node_cli -->|"calls"| node_python_client
node_agent -->|"uses API"| node_python_client
node_python_client -->|"sends requests"| node_http_server
node_http_server -->|"routes requests"| node_chat_ops
node_http_server -->|"routes requests"| node_read_wait
node_http_server -->|"routes requests"| node_file_ops
node_chat_ops -->|"reads and writes"| node_chat_store
node_read_wait -->|"reads and updates"| node_chat_store
node_file_ops -->|"checks attachments"| node_chat_store
node_file_ops -->|"handles bytes"| node_blob_store
node_chat_store -->|"uses rules"| node_access_policy
node_chat_store -->|"uses file storage"| node_blob_store
node_cli -->|"loads settings"| node_settings
node_cli -->|"starts server"| node_http_server
node_cli -->|"opens viewer"| node_viewer_queries
node_http_server -->|"routes viewer requests"| node_viewer_queries
node_viewer_queries -->|"reads state"| node_chat_store
node_viewer_queries -.->|"serves browser view"| node_viewer_page
node_agent -->|"runs evaluation"| node_bench_runner
node_bench_runner -->|"uses client"| node_python_client

click node_cli "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/cli.py"
click node_python_client "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/client.py"
click node_http_server "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/server.py"
click node_chat_ops "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/api.py"
click node_read_wait "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/api.py"
click node_file_ops "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/api.py"
click node_access_policy "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/policy.py"
click node_chat_store "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/store.py"
click node_blob_store "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/files.py"
click node_settings "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/config.py"
click node_viewer_queries "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/view.py"
click node_viewer_page "https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/page/app.js"
click node_bench_runner "https://github.com/pranjal2041/swarmchat/blob/main/extras/programbench/run.py"

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_cli,node_python_client toneBlue
class node_http_server,node_chat_ops,node_read_wait,node_file_ops toneAmber
class node_access_policy,node_chat_store,node_blob_store,node_settings toneMint
class node_viewer_queries,node_viewer_page toneRose
class node_bench_runner,node_agent toneIndigo
```

## Components

### Agent clients

- [Command line](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/cli.py): `swarmchat/cli.py`
- [Python client](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/client.py): `swarmchat/client.py`

### Chat service

- [HTTP server](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/server.py): `swarmchat/server.py`
- [Chat operations](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/api.py): `swarmchat/api.py`
- [Read and wait](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/api.py): `swarmchat/api.py`
- [Attachment operations](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/api.py): `swarmchat/api.py`

### State and policy

- [Roles and permissions](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/policy.py): `swarmchat/policy.py`
- [Chat state](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/store.py): `swarmchat/store.py`
- [Attachment blobs](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/files.py): `swarmchat/files.py`
- [Server settings](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/config.py): `swarmchat/config.py`

### Live viewer

- [Viewer queries](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/view.py): `swarmchat/view.py`
- [Browser viewer](https://github.com/pranjal2041/swarmchat/blob/main/swarmchat/page/app.js): `swarmchat/page/app.js`

### Agent evaluation

- [ProgramBench runner](https://github.com/pranjal2041/swarmchat/blob/main/extras/programbench/run.py): `extras/programbench/run.py`

### Other components

- **Agent or operator**

## Connections

- Agent or operator → Command line: runs commands (evidence: `README.md`)
- Command line → Python client: calls (evidence: `swarmchat/cli.py`)
- Agent or operator → Python client: uses API (evidence: `README.md`)
- Python client → HTTP server: sends requests (evidence: `swarmchat/client.py`)
- HTTP server → Chat operations: routes requests (evidence: `swarmchat/api.py`)
- HTTP server → Read and wait: routes requests (evidence: `swarmchat/api.py`)
- HTTP server → Attachment operations: routes requests (evidence: `swarmchat/api.py`)
- Chat operations → Chat state: reads and writes (evidence: `swarmchat/api.py`)
- Read and wait → Chat state: reads and updates (evidence: `swarmchat/api.py`)
- Attachment operations → Chat state: checks attachments (evidence: `swarmchat/api.py`)
- Attachment operations → Attachment blobs: handles bytes (evidence: `swarmchat/api.py`)
- Chat state → Roles and permissions: uses rules (evidence: `swarmchat/store.py`)
- Chat state → Attachment blobs: uses file storage (evidence: `swarmchat/store.py`)
- Command line → Server settings: loads settings (evidence: `swarmchat/cli.py`)
- Command line → HTTP server: starts server (evidence: `swarmchat/cli.py`)
- Command line → Viewer queries: opens viewer (evidence: `README.md`)
- HTTP server → Viewer queries: routes viewer requests (evidence: `swarmchat/server.py`)
- Viewer queries → Chat state: reads state (evidence: `swarmchat/view.py`)
- Viewer queries → Browser viewer: serves browser view
- Agent or operator → ProgramBench runner: runs evaluation (evidence: `extras/programbench/run.py`)
- ProgramBench runner → Python client: uses client (evidence: `extras/programbench/run.py`)