# selfhoster-sh/pisynapse architecture

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

- Interactive diagram: https://gitdiagram.com/selfhoster-sh/pisynapse
- Repository: https://github.com/selfhoster-sh/pisynapse

## Overview

piSynapse is a self-hosted personal AI assistant whose main workflow takes a user’s chat turn through intent and memory retrieval, local-model response/tool calling, optional verification, and persistence. Tool dispatch fans out to calendar, email, notes, tasks, and weather services; separate branches provide search, accounts/settings, and media features. The excerpts and source index establish the main chat, LLM, tools, and storage links; some feature wiring is documented only in the README, so those links are cited there.

Main entry points: [`routers/chat.py`](https://github.com/selfhoster-sh/pisynapse/blob/main/routers/chat.py) (Chat API), [`llm/chat.py`](https://github.com/selfhoster-sh/pisynapse/blob/main/llm/chat.py) (LLM Bridge), [`tools/dispatcher.py`](https://github.com/selfhoster-sh/pisynapse/blob/main/tools/dispatcher.py) (Tool Dispatcher), [`static/ui.js`](https://github.com/selfhoster-sh/pisynapse/blob/main/static/ui.js) (Web UI and PWA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["Web UI and PWA<br/>[ui.js]"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_media["Voice and Images<br/>[media.py]"]
  node_search["Hybrid Search<br/>[retrieval.py]"]
end

subgraph group_conversation["Conversation Intelligence"]
  node_intent["Intent Routing<br/>[intent.py]"]
  node_memory["Memory and Context<br/>[prompt.py]"]
  node_llm["LLM Bridge<br/>[chat.py]"]
  node_payload["Request Payloads<br/>[payload.py]"]
  node_model{{"Local LLM"}}
end

subgraph group_tools["Tools and Integrations"]
  node_tool_schema["Tool Definitions<br/>[definitions.py]"]
  node_dispatcher["Tool Dispatcher<br/>[dispatcher.py]"]
  node_verification["Tool Verification"]
  node_calendar["Calendar<br/>[calendar_ops.py]"]
  node_email["Email<br/>[mail.py]"]
  node_notes["Notes<br/>[nextcloud_notes.py]"]
  node_tasks["Tasks<br/>[nextcloud_tasks.py]"]
  node_weather["Weather<br/>[weather.py]"]
end

subgraph group_platform["Identity and Storage"]
  node_auth["Accounts and Auth<br/>[auth.py]"]
  node_admin["Admin and Settings<br/>[admin.py]"]
  node_database[("SQLite Store<br/>[db.py]")]
  node_config["Runtime Configuration<br/>[config.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"sends turns"| node_chat_api
node_chat_api -->|"classifies"| node_intent
node_chat_api -->|"retrieves history"| node_search
node_chat_api -->|"builds context"| node_memory
node_chat_api -->|"requests reply"| node_llm
node_llm -->|"builds request"| node_payload
node_payload -->|"adds schemas"| node_tool_schema
node_llm -.->|"calls model"| node_model
node_llm -->|"routes tool calls"| node_dispatcher
node_dispatcher -->|"invokes"| node_calendar
node_dispatcher -->|"invokes"| node_email
node_dispatcher -->|"invokes"| node_notes
node_dispatcher -->|"invokes"| node_tasks
node_dispatcher -->|"invokes"| node_weather
node_llm -->|"verifies calls"| node_verification
node_chat_api -->|"persists turns"| node_database
node_search -->|"queries sessions"| node_database
node_memory -->|"loads context"| node_database
node_media -->|"accepts uploads"| node_user
node_web -->|"searches sessions"| node_search
node_web -->|"submits media"| node_media
node_web -->|"signs in"| node_auth
node_admin -->|"manages users"| node_auth
node_admin -->|"updates records"| node_database
node_chat_api -->|"checks identity"| node_auth
node_chat_api -->|"loads sessions"| node_database
node_llm -.->|"uses calendar context"| node_calendar
node_config -->|"configures backend"| node_llm

click node_web "https://github.com/selfhoster-sh/pisynapse/blob/main/static/ui.js"
click node_chat_api "https://github.com/selfhoster-sh/pisynapse/blob/main/routers/chat.py"
click node_media "https://github.com/selfhoster-sh/pisynapse/blob/main/routers/media.py"
click node_search "https://github.com/selfhoster-sh/pisynapse/blob/main/retrieval.py"
click node_intent "https://github.com/selfhoster-sh/pisynapse/blob/main/llm/intent.py"
click node_memory "https://github.com/selfhoster-sh/pisynapse/blob/main/prompt.py"
click node_llm "https://github.com/selfhoster-sh/pisynapse/blob/main/llm/chat.py"
click node_payload "https://github.com/selfhoster-sh/pisynapse/blob/main/llm/payload.py"
click node_tool_schema "https://github.com/selfhoster-sh/pisynapse/blob/main/tools/definitions.py"
click node_dispatcher "https://github.com/selfhoster-sh/pisynapse/blob/main/tools/dispatcher.py"
click node_verification "https://github.com/selfhoster-sh/pisynapse/blob/main/tool_verification.py"
click node_calendar "https://github.com/selfhoster-sh/pisynapse/blob/main/calendar_ops.py"
click node_email "https://github.com/selfhoster-sh/pisynapse/blob/main/mail.py"
click node_notes "https://github.com/selfhoster-sh/pisynapse/blob/main/nextcloud_notes.py"
click node_tasks "https://github.com/selfhoster-sh/pisynapse/blob/main/nextcloud_tasks.py"
click node_weather "https://github.com/selfhoster-sh/pisynapse/blob/main/weather.py"
click node_auth "https://github.com/selfhoster-sh/pisynapse/blob/main/auth.py"
click node_admin "https://github.com/selfhoster-sh/pisynapse/blob/main/routers/admin.py"
click node_database "https://github.com/selfhoster-sh/pisynapse/blob/main/db.py"
click node_config "https://github.com/selfhoster-sh/pisynapse/blob/main/config.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_web,node_chat_api,node_media,node_search,node_user toneBlue
class node_intent,node_memory,node_llm,node_payload,node_model toneAmber
class node_tool_schema,node_dispatcher,node_verification,node_calendar,node_email,node_notes,node_tasks,node_weather toneMint
class node_auth,node_admin,node_database,node_config toneRose
```

## Components

### User Experience

- [Web UI and PWA](https://github.com/selfhoster-sh/pisynapse/blob/main/static/ui.js): `static/ui.js`
- [Chat API](https://github.com/selfhoster-sh/pisynapse/blob/main/routers/chat.py): `routers/chat.py`
- [Voice and Images](https://github.com/selfhoster-sh/pisynapse/blob/main/routers/media.py): `routers/media.py`
- [Hybrid Search](https://github.com/selfhoster-sh/pisynapse/blob/main/retrieval.py): `retrieval.py`

### Conversation Intelligence

- [Intent Routing](https://github.com/selfhoster-sh/pisynapse/blob/main/llm/intent.py): `llm/intent.py`
- [Memory and Context](https://github.com/selfhoster-sh/pisynapse/blob/main/prompt.py): `prompt.py`
- [LLM Bridge](https://github.com/selfhoster-sh/pisynapse/blob/main/llm/chat.py): `llm/chat.py`
- [Request Payloads](https://github.com/selfhoster-sh/pisynapse/blob/main/llm/payload.py): `llm/payload.py`
- **Local LLM**

### Tools and Integrations

- [Tool Definitions](https://github.com/selfhoster-sh/pisynapse/blob/main/tools/definitions.py): `tools/definitions.py`
- [Tool Dispatcher](https://github.com/selfhoster-sh/pisynapse/blob/main/tools/dispatcher.py): `tools/dispatcher.py`
- [Tool Verification](https://github.com/selfhoster-sh/pisynapse/blob/main/tool_verification.py): `tool_verification.py`
- [Calendar](https://github.com/selfhoster-sh/pisynapse/blob/main/calendar_ops.py): `calendar_ops.py`
- [Email](https://github.com/selfhoster-sh/pisynapse/blob/main/mail.py): `mail.py`
- [Notes](https://github.com/selfhoster-sh/pisynapse/blob/main/nextcloud_notes.py): `nextcloud_notes.py`
- [Tasks](https://github.com/selfhoster-sh/pisynapse/blob/main/nextcloud_tasks.py): `nextcloud_tasks.py`
- [Weather](https://github.com/selfhoster-sh/pisynapse/blob/main/weather.py): `weather.py`

### Identity and Storage

- [Accounts and Auth](https://github.com/selfhoster-sh/pisynapse/blob/main/auth.py): `auth.py`
- [Admin and Settings](https://github.com/selfhoster-sh/pisynapse/blob/main/routers/admin.py): `routers/admin.py`
- [SQLite Store](https://github.com/selfhoster-sh/pisynapse/blob/main/db.py): `db.py`
- [Runtime Configuration](https://github.com/selfhoster-sh/pisynapse/blob/main/config.py): `config.py`

### Other components

- **User**

## Connections

- User → Web UI and PWA: uses
- Web UI and PWA → Chat API: sends turns
- Chat API → Intent Routing: classifies (evidence: `routers/chat.py`)
- Chat API → Hybrid Search: retrieves history (evidence: `routers/chat.py`)
- Chat API → Memory and Context: builds context (evidence: `routers/chat.py`)
- Chat API → LLM Bridge: requests reply (evidence: `routers/chat.py`)
- LLM Bridge → Request Payloads: builds request (evidence: `llm/chat.py`)
- Request Payloads → Tool Definitions: adds schemas (evidence: `llm/payload.py`)
- LLM Bridge → Local LLM: calls model
- LLM Bridge → Tool Dispatcher: routes tool calls (evidence: `llm/chat.py`)
- Tool Dispatcher → Calendar: invokes (evidence: `tools/dispatcher.py`)
- Tool Dispatcher → Email: invokes (evidence: `tools/dispatcher.py`)
- Tool Dispatcher → Notes: invokes (evidence: `tools/dispatcher.py`)
- Tool Dispatcher → Tasks: invokes (evidence: `tools/dispatcher.py`)
- Tool Dispatcher → Weather: invokes (evidence: `tools/dispatcher.py`)
- LLM Bridge → Tool Verification: verifies calls (evidence: `llm/chat.py`)
- Chat API → SQLite Store: persists turns (evidence: `routers/chat.py`)
- Hybrid Search → SQLite Store: queries sessions (evidence: `retrieval.py`)
- Memory and Context → SQLite Store: loads context (evidence: `prompt.py`)
- Voice and Images → User: accepts uploads
- Web UI and PWA → Hybrid Search: searches sessions
- Web UI and PWA → Voice and Images: submits media
- Web UI and PWA → Accounts and Auth: signs in
- Admin and Settings → Accounts and Auth: manages users (evidence: `routers/admin.py`)
- Admin and Settings → SQLite Store: updates records (evidence: `routers/admin.py`)
- Chat API → Accounts and Auth: checks identity (evidence: `routers/chat.py`)
- Chat API → SQLite Store: loads sessions (evidence: `routers/chat.py`)
- LLM Bridge → Calendar: uses calendar context (evidence: `llm/chat.py`)
- Runtime Configuration → LLM Bridge: configures backend (evidence: `config.py`)
