# chrisroyse/synapse architecture

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

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

## Overview

Synapse is a local Windows automation runtime that exposes desktop perception and control to AI models through MCP. The principal loop is an agent request, MCP tool dispatch, observation of the desktop or browser, a guarded action, and a returned result; durable agent, audit, and timeline state supports ongoing work. The tree and README support these major capability areas, but the sampled excerpts do not expose most tool-handler wiring, so subsystem links below reflect documented behavior rather than claims of inspected call sites.

Main entry points: [`crates/synapse-mcp/src/server/m1_tools/mod.rs`](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server/m1_tools/mod.rs) (Tool handlers), [`crates/synapse-perception/src/observe.rs`](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-perception/src/observe.rs) (Observe and find), [`crates/synapse-mcp/src/server.rs`](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server.rs) (MCP server), [`crates/synapse-storage/src/lib.rs`](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-storage/src/lib.rs) (Durable state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["MCP Gateway"]
  node_gateway["MCP server<br/>[server.rs]"]
  node_transport["MCP transports<br/>[transport.rs]"]
  node_toolsets["Tool handlers<br/>[mod.rs]"]
end

subgraph group_senses["Perception"]
  node_screenshot["Screen capture<br/>[lib.rs]"]
  node_accessibility["UI Automation<br/>[lib.rs]"]
  node_perception["Observe and find<br/>[observe.rs]"]
  node_ocr["OCR and text<br/>[ocr.rs]"]
  node_browser["Browser tools<br/>[browser_facades.rs]"]
  node_audio["Audio sensing<br/>[lib.rs]"]
end

subgraph group_control["Desktop Control"]
  node_action_tools["Action tools<br/>[m2.rs]"]
  node_action["Input execution<br/>[lib.rs]"]
end

subgraph group_continuity["Agent Continuity"]
  node_reflex["Reflex runtime<br/>[runtime.rs]"]
  node_storage[("Durable state<br/>[lib.rs]")]
  node_agent_ops["Agent operations<br/>[agent_query.rs]"]
  node_routines["Routines and plans<br/>[routines.rs]"]
end

subgraph group_operator["Operator UI"]
  node_dashboard["Dashboard<br/>[app.tsx]"]
  node_overlay["Tray companion<br/>[main.rs]"]
end

node_agent(("AI agent"))
node_chrome["Chrome extension<br/>[service_worker.js]"]
node_windows["Windows desktop"]
node_daemon["Synapse daemon<br/>[main.rs]"]

node_agent -->|"sends MCP requests"| node_transport
node_transport -->|"delivers requests"| node_gateway
node_gateway -->|"dispatches tools"| node_toolsets
node_toolsets -->|"requests observation"| node_perception
node_perception -->|"captures frames"| node_screenshot
node_perception -->|"reads UI tree"| node_accessibility
node_perception -->|"extracts text"| node_ocr
node_toolsets -->|"dispatches browser tools"| node_browser
node_browser -->|"sends browser commands"| node_chrome
node_toolsets -->|"dispatches actions"| node_action_tools
node_action_tools -->|"executes input"| node_action
node_action -->|"controls desktop"| node_windows
node_screenshot -->|"captures screen"| node_windows
node_accessibility -->|"reads controls"| node_windows
node_toolsets -.->|"requests audio"| node_audio
node_gateway -->|"uses runtime"| node_reflex
node_reflex -->|"persists state"| node_storage
node_agent_ops -->|"reads agent records"| node_storage
node_routines -->|"uses durable state"| node_storage
node_dashboard -->|"queries and controls"| node_daemon
node_overlay -->|"queries daemon"| node_daemon

click node_gateway "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server.rs"
click node_transport "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/http/transport.rs"
click node_toolsets "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server/m1_tools/mod.rs"
click node_screenshot "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-capture/src/lib.rs"
click node_accessibility "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-a11y/src/lib.rs"
click node_perception "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-perception/src/observe.rs"
click node_ocr "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-perception/src/ocr.rs"
click node_browser "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server/browser_facades.rs"
click node_chrome "https://github.com/chrisroyse/synapse/blob/main/extensions/synapse-chrome-debugger/service_worker.js"
click node_action_tools "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/m2.rs"
click node_action "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-action/src/lib.rs"
click node_audio "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-audio/src/lib.rs"
click node_reflex "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-reflex/src/runtime.rs"
click node_storage "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-storage/src/lib.rs"
click node_agent_ops "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server/agent_query.rs"
click node_routines "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/m3/routines.rs"
click node_dashboard "https://github.com/chrisroyse/synapse/blob/main/dashboard/src/app.tsx"
click node_overlay "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-overlay/src/main.rs"
click node_daemon "https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/main.rs"

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_gateway,node_transport,node_toolsets toneBlue
class node_screenshot,node_accessibility,node_perception,node_ocr,node_browser,node_audio toneAmber
class node_action_tools,node_action toneMint
class node_reflex,node_storage,node_agent_ops,node_routines toneRose
class node_dashboard,node_overlay,node_agent,node_windows toneIndigo
class node_chrome,node_daemon toneTeal
```

## Components

### MCP Gateway

- [MCP server](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server.rs): `crates/synapse-mcp/src/server.rs`
- [MCP transports](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/http/transport.rs): `crates/synapse-mcp/src/http/transport.rs`
- [Tool handlers](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server/m1_tools/mod.rs): `crates/synapse-mcp/src/server/m1_tools/mod.rs`

### Perception

- [Screen capture](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-capture/src/lib.rs): `crates/synapse-capture/src/lib.rs`
- [UI Automation](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-a11y/src/lib.rs): `crates/synapse-a11y/src/lib.rs`
- [Observe and find](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-perception/src/observe.rs): `crates/synapse-perception/src/observe.rs`
- [OCR and text](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-perception/src/ocr.rs): `crates/synapse-perception/src/ocr.rs`
- [Browser tools](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server/browser_facades.rs): `crates/synapse-mcp/src/server/browser_facades.rs`
- [Audio sensing](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-audio/src/lib.rs): `crates/synapse-audio/src/lib.rs`

### Desktop Control

- [Action tools](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/m2.rs): `crates/synapse-mcp/src/m2.rs`
- [Input execution](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-action/src/lib.rs): `crates/synapse-action/src/lib.rs`

### Agent Continuity

- [Reflex runtime](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-reflex/src/runtime.rs): `crates/synapse-reflex/src/runtime.rs`
- [Durable state](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-storage/src/lib.rs): `crates/synapse-storage/src/lib.rs`
- [Agent operations](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/server/agent_query.rs): `crates/synapse-mcp/src/server/agent_query.rs`
- [Routines and plans](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/m3/routines.rs): `crates/synapse-mcp/src/m3/routines.rs`

### Operator UI

- [Dashboard](https://github.com/chrisroyse/synapse/blob/main/dashboard/src/app.tsx): `dashboard/src/app.tsx`
- [Tray companion](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-overlay/src/main.rs): `crates/synapse-overlay/src/main.rs`

### Other components

- **AI agent**
- [Chrome extension](https://github.com/chrisroyse/synapse/blob/main/extensions/synapse-chrome-debugger/service_worker.js): `extensions/synapse-chrome-debugger/service_worker.js`
- **Windows desktop**
- [Synapse daemon](https://github.com/chrisroyse/synapse/blob/main/crates/synapse-mcp/src/main.rs): `crates/synapse-mcp/src/main.rs`

## Connections

- AI agent → MCP transports: sends MCP requests
- MCP transports → MCP server: delivers requests
- MCP server → Tool handlers: dispatches tools
- Tool handlers → Observe and find: requests observation
- Observe and find → Screen capture: captures frames
- Observe and find → UI Automation: reads UI tree
- Observe and find → OCR and text: extracts text
- Tool handlers → Browser tools: dispatches browser tools
- Browser tools → Chrome extension: sends browser commands
- Tool handlers → Action tools: dispatches actions
- Action tools → Input execution: executes input
- Input execution → Windows desktop: controls desktop
- Screen capture → Windows desktop: captures screen
- UI Automation → Windows desktop: reads controls
- Tool handlers → Audio sensing: requests audio
- MCP server → Reflex runtime: uses runtime
- Reflex runtime → Durable state: persists state
- Agent operations → Durable state: reads agent records
- Routines and plans → Durable state: uses durable state
- Dashboard → Synapse daemon: queries and controls
- Tray companion → Synapse daemon: queries daemon