# saahilpal/synapse architecture

> Architecture diagram of the GitHub repository saahilpal/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/saahilpal/synapse
- Repository: https://github.com/saahilpal/synapse

## Overview

Synap is a local, Git-aware structural context engine for coding agents. Its main workflow watches repository changes, indexes source structure into SQLite, and serves token-bounded context through MCP retrieval. Separate capabilities include generated wiki pages, branch-persistent checkpoints and lessons, and a diagnostic API. The graph follows the README’s runtime design and relationships visible in excerpts or the SOURCE INDEX; unsampled implementation details are represented only where documented, and uncertain connections are omitted.

Main entry points: [`src/synap_git/indexer/engine.py`](https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/engine.py) (Runtime and Indexer), [`src/synap_git/storage/sqlite.py`](https://github.com/saahilpal/synapse/blob/main/src/synap_git/storage/sqlite.py) (SQLite Knowledge Store), [`src/synap_git/indexer/daemon.py`](https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/daemon.py) (Runtime Daemon), [`src/synap_git/cli/main.py`](https://github.com/saahilpal/synapse/blob/main/src/synap_git/cli/main.py) (CLI Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and Git"]
  node_cli["CLI Commands<br/>[main.py]"]
  node_daemon["Runtime Daemon<br/>[daemon.py]"]
  node_git_state["Git State Watcher<br/>[state.py]"]
  node_api["Diagnostic API<br/>[app.py]"]
end

subgraph group_index["Indexing and Knowledge"]
  node_engine["Runtime and Indexer<br/>[engine.py]"]
  node_scanner["File Scanner<br/>[scanner.py]"]
  node_parser["Structural Parser<br/>[registry.py]"]
  node_sqlite[("SQLite Knowledge Store<br/>[sqlite.py]")]
  node_wiki["Semantic Wiki<br/>[wiki.py]"]
end

subgraph group_agent["Agent Context"]
  node_retrieval["Hybrid Retrieval<br/>[engine.py]"]
  node_memory["Behavioral Memory<br/>[memory.py]"]
  node_mcp["MCP Tool Server<br/>[server.py]"]
  node_checkpoint_cli["Checkpoint Commands<br/>[checkpoint.py]"]
  node_lesson_cli["Lesson Commands<br/>[lessons.py]"]
end

subgraph group_integrations["Providers and Diagnostics"]
  node_settings["Configuration<br/>[config.py]"]
  node_provider_factory["Provider Factory<br/>[factory.py]"]
  node_provider_base["Provider Interface<br/>[base.py]"]
  node_openai_provider["OpenAI Provider<br/>[openai.py]"]
  node_logger["Structured Logging<br/>[logger.py]"]
end

node_developer(("Developer"))
node_agent_client(("AI Coding Agent"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"invokes"| node_daemon
node_daemon -->|"starts watcher"| node_git_state
node_daemon -->|"coordinates indexing"| node_engine
node_daemon -->|"hosts server"| node_api
node_git_state -->|"detects commit changes"| node_engine
node_engine -->|"scans files"| node_scanner
node_engine -->|"parses source"| node_parser
node_engine -->|"stores index"| node_sqlite
node_parser -->|"uses language mapping"| node_scanner
node_engine -->|"generates documentation"| node_wiki
node_wiki -->|"uses wiki queue"| node_sqlite
node_agent_client -->|"calls tools"| node_mcp
node_mcp -->|"delegates runtime calls"| node_engine
node_engine -->|"runs queries"| node_retrieval
node_retrieval -->|"searches graph and symbols"| node_sqlite
node_mcp -->|"records agent memory"| node_sqlite
node_checkpoint_cli -.->|"manages checkpoints"| node_sqlite
node_lesson_cli -->|"uses runtime"| node_engine
node_lesson_cli -.->|"manages lessons"| node_sqlite
node_api -->|"reads status and traces"| node_engine
node_cli -->|"configures runtime"| node_settings
node_engine -->|"initializes from"| node_settings
node_engine -->|"creates providers"| node_provider_factory
node_provider_factory -->|"wraps providers"| node_provider_base
node_provider_factory -->|"selects provider"| node_openai_provider
node_engine -->|"records operations"| node_logger

click node_cli "https://github.com/saahilpal/synapse/blob/main/src/synap_git/cli/main.py"
click node_daemon "https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/daemon.py"
click node_git_state "https://github.com/saahilpal/synapse/blob/main/src/synap_git/git/state.py"
click node_engine "https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/engine.py"
click node_scanner "https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/scanner.py"
click node_parser "https://github.com/saahilpal/synapse/blob/main/src/synap_git/parser/registry.py"
click node_sqlite "https://github.com/saahilpal/synapse/blob/main/src/synap_git/storage/sqlite.py"
click node_wiki "https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/wiki.py"
click node_retrieval "https://github.com/saahilpal/synapse/blob/main/src/synap_git/retrieval/engine.py"
click node_memory "https://github.com/saahilpal/synapse/blob/main/src/synap_git/retrieval/memory.py"
click node_mcp "https://github.com/saahilpal/synapse/blob/main/src/synap_git/mcp/server.py"
click node_checkpoint_cli "https://github.com/saahilpal/synapse/blob/main/src/synap_git/cli/checkpoint.py"
click node_lesson_cli "https://github.com/saahilpal/synapse/blob/main/src/synap_git/cli/lessons.py"
click node_api "https://github.com/saahilpal/synapse/blob/main/src/synap_git/api/app.py"
click node_settings "https://github.com/saahilpal/synapse/blob/main/src/synap_git/config.py"
click node_provider_factory "https://github.com/saahilpal/synapse/blob/main/src/synap_git/provider/factory.py"
click node_provider_base "https://github.com/saahilpal/synapse/blob/main/src/synap_git/provider/base.py"
click node_openai_provider "https://github.com/saahilpal/synapse/blob/main/src/synap_git/provider/openai.py"
click node_logger "https://github.com/saahilpal/synapse/blob/main/src/synap_git/diagnostics/logger.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_daemon,node_git_state,node_api toneBlue
class node_engine,node_scanner,node_parser,node_sqlite,node_wiki toneAmber
class node_retrieval,node_memory,node_mcp,node_checkpoint_cli,node_lesson_cli toneMint
class node_settings,node_provider_factory,node_provider_base,node_openai_provider,node_logger toneRose
class node_developer,node_agent_client toneIndigo
```

## Components

### Runtime and Git

- [CLI Commands](https://github.com/saahilpal/synapse/blob/main/src/synap_git/cli/main.py): `src/synap_git/cli/main.py`
- [Runtime Daemon](https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/daemon.py): `src/synap_git/indexer/daemon.py`
- [Git State Watcher](https://github.com/saahilpal/synapse/blob/main/src/synap_git/git/state.py): `src/synap_git/git/state.py`
- [Diagnostic API](https://github.com/saahilpal/synapse/blob/main/src/synap_git/api/app.py): `src/synap_git/api/app.py`

### Indexing and Knowledge

- [Runtime and Indexer](https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/engine.py): `src/synap_git/indexer/engine.py`
- [File Scanner](https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/scanner.py): `src/synap_git/indexer/scanner.py`
- [Structural Parser](https://github.com/saahilpal/synapse/blob/main/src/synap_git/parser/registry.py): `src/synap_git/parser/registry.py`
- [SQLite Knowledge Store](https://github.com/saahilpal/synapse/blob/main/src/synap_git/storage/sqlite.py): `src/synap_git/storage/sqlite.py`
- [Semantic Wiki](https://github.com/saahilpal/synapse/blob/main/src/synap_git/indexer/wiki.py): `src/synap_git/indexer/wiki.py`

### Agent Context

- [Hybrid Retrieval](https://github.com/saahilpal/synapse/blob/main/src/synap_git/retrieval/engine.py): `src/synap_git/retrieval/engine.py`
- [Behavioral Memory](https://github.com/saahilpal/synapse/blob/main/src/synap_git/retrieval/memory.py): `src/synap_git/retrieval/memory.py`
- [MCP Tool Server](https://github.com/saahilpal/synapse/blob/main/src/synap_git/mcp/server.py): `src/synap_git/mcp/server.py`
- [Checkpoint Commands](https://github.com/saahilpal/synapse/blob/main/src/synap_git/cli/checkpoint.py): `src/synap_git/cli/checkpoint.py`
- [Lesson Commands](https://github.com/saahilpal/synapse/blob/main/src/synap_git/cli/lessons.py): `src/synap_git/cli/lessons.py`

### Providers and Diagnostics

- [Configuration](https://github.com/saahilpal/synapse/blob/main/src/synap_git/config.py): `src/synap_git/config.py`
- [Provider Factory](https://github.com/saahilpal/synapse/blob/main/src/synap_git/provider/factory.py): `src/synap_git/provider/factory.py`
- [Provider Interface](https://github.com/saahilpal/synapse/blob/main/src/synap_git/provider/base.py): `src/synap_git/provider/base.py`
- [OpenAI Provider](https://github.com/saahilpal/synapse/blob/main/src/synap_git/provider/openai.py): `src/synap_git/provider/openai.py`
- [Structured Logging](https://github.com/saahilpal/synapse/blob/main/src/synap_git/diagnostics/logger.py): `src/synap_git/diagnostics/logger.py`

### Other components

- **Developer**
- **AI Coding Agent**

## Connections

- Developer → CLI Commands: runs commands
- CLI Commands → Runtime Daemon: invokes (evidence: `src/synap_git/cli/main.py`)
- Runtime Daemon → Git State Watcher: starts watcher
- Runtime Daemon → Runtime and Indexer: coordinates indexing (evidence: `src/synap_git/indexer/daemon.py`)
- Runtime Daemon → Diagnostic API: hosts server (evidence: `src/synap_git/indexer/daemon.py`)
- Git State Watcher → Runtime and Indexer: detects commit changes
- Runtime and Indexer → File Scanner: scans files (evidence: `src/synap_git/indexer/engine.py`)
- Runtime and Indexer → Structural Parser: parses source (evidence: `src/synap_git/indexer/engine.py`)
- Runtime and Indexer → SQLite Knowledge Store: stores index (evidence: `src/synap_git/indexer/engine.py`)
- Structural Parser → File Scanner: uses language mapping (evidence: `src/synap_git/parser/registry.py`)
- Runtime and Indexer → Semantic Wiki: generates documentation (evidence: `src/synap_git/indexer/engine.py`)
- Semantic Wiki → SQLite Knowledge Store: uses wiki queue (evidence: `src/synap_git/indexer/wiki.py`)
- AI Coding Agent → MCP Tool Server: calls tools
- MCP Tool Server → Runtime and Indexer: delegates runtime calls (evidence: `src/synap_git/mcp/server.py`)
- Runtime and Indexer → Hybrid Retrieval: runs queries (evidence: `src/synap_git/indexer/engine.py`)
- Hybrid Retrieval → SQLite Knowledge Store: searches graph and symbols (evidence: `src/synap_git/retrieval/engine.py`)
- MCP Tool Server → SQLite Knowledge Store: records agent memory (evidence: `src/synap_git/mcp/server.py`)
- Checkpoint Commands → SQLite Knowledge Store: manages checkpoints
- Lesson Commands → Runtime and Indexer: uses runtime (evidence: `src/synap_git/cli/lessons.py`)
- Lesson Commands → SQLite Knowledge Store: manages lessons
- Diagnostic API → Runtime and Indexer: reads status and traces (evidence: `src/synap_git/api/app.py`)
- CLI Commands → Configuration: configures runtime (evidence: `src/synap_git/cli/main.py`)
- Runtime and Indexer → Configuration: initializes from (evidence: `src/synap_git/indexer/engine.py`)
- Runtime and Indexer → Provider Factory: creates providers (evidence: `src/synap_git/indexer/engine.py`)
- Provider Factory → Provider Interface: wraps providers (evidence: `src/synap_git/provider/factory.py`)
- Provider Factory → OpenAI Provider: selects provider (evidence: `src/synap_git/provider/factory.py`)
- Runtime and Indexer → Structured Logging: records operations (evidence: `src/synap_git/indexer/engine.py`)
