# milkslayer/synapse architecture

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

- Interactive diagram: https://gitdiagram.com/milkslayer/synapse
- Repository: https://github.com/milkslayer/synapse

## Overview

Synapse is a real-time messaging and team-coordination system for Claude Code agent fleets and human operators. A typical workflow starts when an agent uses MCP tools to register, claim a role, join a team, or send a message. The server maintains identities and team membership, routes messages, and records per-instance events; the channel plugin polls those events and pushes them into Claude Code to trigger agent turns. The README documents the operator UI and broader team workflow. Source excerpts are partial, so internal server relationships are shown only where supported.

Main entry points: [`server/synapse_v2.py`](https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py) (HTTP API), [`mcp-bridge/server_v2.py`](https://github.com/milkslayer/synapse/blob/master/mcp-bridge/server_v2.py) (Registration and identity sync), [`channel-plugin/server.js`](https://github.com/milkslayer/synapse/blob/master/channel-plugin/server.js) (Channel MCP plugin), [`mcp-bridge/session_map_hook.py`](https://github.com/milkslayer/synapse/blob/master/mcp-bridge/session_map_hook.py) (Session mapping hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Messaging server"]
  node_http_api["HTTP API<br/>[synapse_v2.py]"]
  node_identity["Identity and presence<br/>[synapse_v2.py]"]
  node_team_roles["Teams, roles, invites<br/>[synapse_v2.py]"]
  node_message_routing["Message routing<br/>[synapse_v2.py]"]
  node_event_stream["Instance event stream<br/>[synapse_v2.py]"]
  node_sqlite[("SQLite state<br/>[synapse_v2.py]")]
end

subgraph group_bridge["MCP bridge"]
  node_mcp_tools["Synapse MCP tools<br/>[server_v2.py]"]
  node_bridge_identity["Registration and identity sync<br/>[server_v2.py]"]
  node_session_hook["Session mapping hook"]
end

subgraph group_channel["Channel delivery"]
  node_channel_server["Channel MCP plugin<br/>[server.js]"]
end

subgraph group_operator["Operator interface"]
  node_operator_ui["Operator web UI<br/>[ui_v2.html]"]
end

node_human(("Human operator"))
node_claude(("Claude Code session"))
node_lease_file["Session lease files"]

node_human -->|"operates"| node_operator_ui
node_operator_ui -->|"uses server"| node_http_api
node_claude -->|"invokes tools"| node_mcp_tools
node_mcp_tools -->|"calls endpoints"| node_http_api
node_bridge_identity -->|"registers identity"| node_http_api
node_http_api -->|"handles identity routes"| node_identity
node_http_api -->|"handles team routes"| node_team_roles
node_http_api -->|"handles send requests"| node_message_routing
node_message_routing -->|"records recipient events"| node_event_stream
node_identity -->|"reads and writes"| node_sqlite
node_team_roles -->|"reads and writes"| node_sqlite
node_message_routing -->|"reads and writes"| node_sqlite
node_event_stream -->|"reads and writes"| node_sqlite
node_channel_server -->|"polls events"| node_event_stream
node_channel_server -->|"pushes channel events"| node_claude
node_bridge_identity -->|"writes lease"| node_lease_file
node_channel_server -->|"reads lease"| node_lease_file
node_session_hook -->|"writes session maps"| node_lease_file
node_bridge_identity -->|"reads session mapping"| node_session_hook

click node_mcp_tools "https://github.com/milkslayer/synapse/blob/master/mcp-bridge/server_v2.py"
click node_bridge_identity "https://github.com/milkslayer/synapse/blob/master/mcp-bridge/server_v2.py"
click node_session_hook "https://github.com/milkslayer/synapse/blob/master/mcp-bridge/session_map_hook.py"
click node_http_api "https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py"
click node_identity "https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py"
click node_team_roles "https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py"
click node_message_routing "https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py"
click node_event_stream "https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py"
click node_sqlite "https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py"
click node_operator_ui "https://github.com/milkslayer/synapse/blob/master/server/ui_v2.html"
click node_channel_server "https://github.com/milkslayer/synapse/blob/master/channel-plugin/server.js"

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_http_api,node_identity,node_team_roles,node_message_routing,node_event_stream,node_sqlite toneBlue
class node_mcp_tools,node_bridge_identity,node_session_hook toneAmber
class node_channel_server toneMint
class node_operator_ui toneRose
class node_human,node_claude,node_lease_file toneIndigo
```

## Components

### Messaging server

- [HTTP API](https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py): `server/synapse_v2.py`
- [Identity and presence](https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py): `server/synapse_v2.py`
- [Teams, roles, invites](https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py): `server/synapse_v2.py`
- [Message routing](https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py): `server/synapse_v2.py`
- [Instance event stream](https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py): `server/synapse_v2.py`
- [SQLite state](https://github.com/milkslayer/synapse/blob/master/server/synapse_v2.py): `server/synapse_v2.py`

### MCP bridge

- [Synapse MCP tools](https://github.com/milkslayer/synapse/blob/master/mcp-bridge/server_v2.py): `mcp-bridge/server_v2.py`
- [Registration and identity sync](https://github.com/milkslayer/synapse/blob/master/mcp-bridge/server_v2.py): `mcp-bridge/server_v2.py`
- [Session mapping hook](https://github.com/milkslayer/synapse/blob/master/mcp-bridge/session_map_hook.py): `mcp-bridge/session_map_hook.py`

### Channel delivery

- [Channel MCP plugin](https://github.com/milkslayer/synapse/blob/master/channel-plugin/server.js): `channel-plugin/server.js`

### Operator interface

- [Operator web UI](https://github.com/milkslayer/synapse/blob/master/server/ui_v2.html): `server/ui_v2.html`

### Other components

- **Human operator**
- **Claude Code session**
- **Session lease files**

## Connections

- Human operator → Operator web UI: operates (evidence: `README.md`)
- Operator web UI → HTTP API: uses server (evidence: `README.md`)
- Claude Code session → Synapse MCP tools: invokes tools (evidence: `README.md`)
- Synapse MCP tools → HTTP API: calls endpoints (evidence: `mcp-bridge/server_v2.py`)
- Registration and identity sync → HTTP API: registers identity (evidence: `mcp-bridge/server_v2.py`)
- HTTP API → Identity and presence: handles identity routes (evidence: `server/synapse_v2.py`)
- HTTP API → Teams, roles, invites: handles team routes (evidence: `server/synapse_v2.py`)
- HTTP API → Message routing: handles send requests (evidence: `server/synapse_v2.py`)
- Message routing → Instance event stream: records recipient events (evidence: `README.md`)
- Identity and presence → SQLite state: reads and writes (evidence: `server/synapse_v2.py`)
- Teams, roles, invites → SQLite state: reads and writes (evidence: `server/synapse_v2.py`)
- Message routing → SQLite state: reads and writes (evidence: `server/synapse_v2.py`)
- Instance event stream → SQLite state: reads and writes (evidence: `server/synapse_v2.py`)
- Channel MCP plugin → Instance event stream: polls events (evidence: `channel-plugin/server.js`)
- Channel MCP plugin → Claude Code session: pushes channel events (evidence: `channel-plugin/server.js`)
- Registration and identity sync → Session lease files: writes lease (evidence: `mcp-bridge/server_v2.py`)
- Channel MCP plugin → Session lease files: reads lease (evidence: `channel-plugin/server.js`)
- Session mapping hook → Session lease files: writes session maps (evidence: `mcp-bridge/session_map_hook.py`)
- Registration and identity sync → Session mapping hook: reads session mapping (evidence: `mcp-bridge/server_v2.py`)
