# siyuan-note/siyuan architecture

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

- Interactive diagram: https://gitdiagram.com/siyuan-note/siyuan
- Repository: https://github.com/siyuan-note/siyuan
- Video tour (about a minute): https://gitdiagram.com/siyuan-note/siyuan/video

## Overview

#### Purpose and delivery modes
SiYuan is a privacy-first personal knowledge-management system centered on block-based Markdown WYSIWYG documents, references, assets, databases, search, export, sync, plugins, and AI. It ships as a desktop Electron app, browser-accessible Docker service, and direct workspace CLI. Core entry points are `kernel/main.go`, `kernel/cli/cmd/root.go`, `app/electron/main.js`, and `app/src/index.ts`.

#### Runtime split and startup
The Go kernel owns workspace state and exposes local HTTP/WebSocket APIs. It initializes the server and routes requests through `kernel/server/serve.go` and `kernel/api/router.go`. The TypeScript frontend is a browser renderer that boots UI, fetches configuration, and registers global input handling via `app/src/index.ts`, `app/src/boot/onGetConfig.ts`, and `app/src/boot/globalEvent/event.ts`. Electron hosts this renderer and kernel-facing desktop behavior through `app/electron/main.js`.

#### Workspace and persistence boundary
User data lives in an externally selected workspace rather than repository source: notebook directories contain JSON `.sy` document files; assets, storage, templates, plugins, and other workspace content are adjacent. The kernel’s document/filesystem model, tree representation, and SQL/index layers are concentrated in `kernel/model/filesys_init.go`, `kernel/model/tree.go`, `kernel/treenode/tree.go`, `kernel/sql/database.go`, and `kernel/sql/index_queue.go`. This boundary is critical for Docker volume mounts and CLI operations.

#### Content editing and rendering
The Protyle editor is the primary client-side document surface. Input, block operations, transactions, undo, uploads, and rich rendering flow through `app/src/protyle/index.ts`, `app/src/protyle/wysiwyg/transaction.ts`, `app/src/protyle/undo/index.ts`, and `app/src/protyle/render/blockRender.ts`. Rendering delegates specialized content to bundled engines (math, diagrams, charts, PDF) under `app/stage/protyle/js/` and PDF viewer code in `app/src/asset/pdf/`. Kernel block APIs and models are the server-side counterpart: `kernel/api/block.go`, `kernel/api/transaction.go`, and `kernel/model/block.go`.

#### Application shell and knowledge navigation
The desktop UI manages tabs, split panes, windows, docks, menus, search, history, and mobile variants. The layout model is anchored in `app/src/layout/Model.ts`, `app/src/layout/Tab.ts`, and `app/src/layout/index.ts`; navigator surfaces include files, backlinks, outline, tags, and graph under `app/src/layout/dock/`. Search and graph requests cross into kernel APIs implemented by `kernel/api/search.go`, `kernel/model/search.go`, `kernel/api/graph.go`, and `kernel/model/graph.go`.

#### Extensibility, marketplace, and AI
Plugins execute behind a kernel-managed API/RPC/WebSocket boundary (`kernel/plugin/manager.go`, `kernel/plugin/server.go`, `kernel/plugin/sandbox.go`), while the frontend exposes plugin APIs through `app/src/plugin/API.ts` and `app/src/plugin/loader.ts`. Marketplace package installation is handled in `kernel/bazaar/install.go`. AI chat/agent flows span frontend chat UI (`app/src/ai/chat.ts`, `app/src/layout/dock/agent/agentSSE.ts`) and kernel streaming/tool execution (`kernel/agent/runtime.go`, `kernel/agent/tools.go`, `kernel/api/agent.go`). MCP client/server support is implemented under `kernel/mcp/`.

#### Deployment and external integrations
Desktop packaging uses Electron Builder configurations in `app/electron-builder.yml` and platform variants; bundled Pandoc supports exports under `app/pandoc/`. Docker starts `kernel/entrypoint.sh` from `Dockerfile`, then runs the kernel `serve` command with a mounted workspace; reverse proxies must support `/ws`. External-facing integrations include OpenAI-compatible AI providers, cloud sync/account services, WebDAV/CardDAV/CalDAV models, OCR, Pandoc, marketplace content, and MCP tools; relevant boundaries include `kernel/model/cloud_service.go`, `kernel/model/dav.go`, `kernel/util/openai.go`, and `kernel/util/pandoc.go`.

Main entry points: [`kernel/api/router.go`](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/router.go) (API router), [`app/src/index.ts`](https://github.com/siyuan-note/siyuan/blob/master/app/src/index.ts) (Browser frontend), [`kernel/model/filesys_init.go`](https://github.com/siyuan-note/siyuan/blob/master/kernel/model/filesys_init.go) (Document filesystem model), [`kernel/main.go`](https://github.com/siyuan-note/siyuan/blob/master/kernel/main.go) (Kernel entrypoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client runtimes"]
  node_electron["Electron host<br/>desktop runtime<br/>[main.js]"]
  node_frontend["Browser frontend<br/>TypeScript renderer<br/>[index.ts]"]
  node_boot["Client boot<br/>configuration and events<br/>[onGetConfig.ts]"]
  node_shell["Workspace shell<br/>tabs and layout<br/>[Model.ts]"]
  node_editor["Protyle editor<br/>block WYSIWYG<br/>[index.ts]"]
  node_renderer["Rich content renderers<br/>math diagram chart PDF<br/>[blockRender.ts]"]
  node_plugin_ui["Plugin frontend API<br/>plugin bridge<br/>[API.ts]"]
  node_ai_ui["AI chat UI<br/>streaming chat<br/>[chat.ts]"]
end

subgraph group_kernel["Go kernel"]
  node_kernel_main{{"Kernel entrypoint<br/>Go runtime<br/>[main.go]"}}
  node_server["HTTP and WebSocket server<br/>local API server<br/>[serve.go]"]
  node_router["API router<br/>request boundary<br/>[router.go]"]
  node_blocks["Block transactions<br/>document API and model<br/>[transaction.go]"]
  node_search_graph["Search and graph<br/>indexed knowledge queries<br/>[search.go]"]
  node_docker["Docker service<br/>container delivery"]
end

subgraph group_workspace["Workspace data"]
  node_workspace_model["Document filesystem model<br/>notebooks and trees<br/>[filesys_init.go]"]
  node_index_db[("SQL index and queue<br/>search persistence<br/>[database.go]")]
  node_workspace_files[("Mounted workspace<br/>documents and assets")]
end

subgraph group_extension["Extensions and integrations"]
  node_plugins["Plugin runtime<br/>RPC WebSocket sandbox<br/>[manager.go]"]
  node_ai_agent["AI agent runtime<br/>streaming tools<br/>[runtime.go]"]
  node_external(("External services<br/>[cloud_service.go]"))
  node_pandoc["Pandoc export<br/>bundled converter"]
end

node_electron -->|"hosts renderer"| node_frontend
node_frontend -->|"initializes"| node_boot
node_frontend -->|"builds UI"| node_shell
node_shell -->|"opens documents"| node_editor
node_editor -->|"renders blocks"| node_renderer
node_frontend -->|"HTTP / WebSocket"| node_router
node_kernel_main -->|"starts"| node_server
node_server -->|"routes requests"| node_router
node_router -->|"block APIs"| node_blocks
node_router -->|"knowledge queries"| node_search_graph
node_blocks -->|"reads and writes"| node_workspace_model
node_workspace_model -->|"manages"| node_workspace_files
node_workspace_model -->|"indexes"| node_index_db
node_search_graph -->|"queries"| node_index_db
node_router -->|"plugin RPC"| node_plugins
node_plugin_ui -->|"frontend bridge"| node_plugins
node_router -->|"agent API"| node_ai_agent
node_ai_ui -->|"streaming chat"| node_ai_agent
node_plugins -->|"marketplace and services"| node_external
node_ai_agent -->|"providers and MCP tools"| node_external
node_kernel_main -->|"exports through"| node_pandoc
node_docker -->|"runs serve"| node_kernel_main
node_docker -->|"mounts"| node_workspace_files

click node_electron "https://github.com/siyuan-note/siyuan/blob/master/app/electron/main.js"
click node_frontend "https://github.com/siyuan-note/siyuan/blob/master/app/src/index.ts"
click node_boot "https://github.com/siyuan-note/siyuan/blob/master/app/src/boot/onGetConfig.ts"
click node_shell "https://github.com/siyuan-note/siyuan/blob/master/app/src/layout/Model.ts"
click node_editor "https://github.com/siyuan-note/siyuan/blob/master/app/src/protyle/index.ts"
click node_renderer "https://github.com/siyuan-note/siyuan/blob/master/app/src/protyle/render/blockRender.ts"
click node_plugin_ui "https://github.com/siyuan-note/siyuan/blob/master/app/src/plugin/API.ts"
click node_ai_ui "https://github.com/siyuan-note/siyuan/blob/master/app/src/ai/chat.ts"
click node_kernel_main "https://github.com/siyuan-note/siyuan/blob/master/kernel/main.go"
click node_server "https://github.com/siyuan-note/siyuan/blob/master/kernel/server/serve.go"
click node_router "https://github.com/siyuan-note/siyuan/blob/master/kernel/api/router.go"
click node_blocks "https://github.com/siyuan-note/siyuan/blob/master/kernel/api/transaction.go"
click node_search_graph "https://github.com/siyuan-note/siyuan/blob/master/kernel/api/search.go"
click node_workspace_model "https://github.com/siyuan-note/siyuan/blob/master/kernel/model/filesys_init.go"
click node_index_db "https://github.com/siyuan-note/siyuan/blob/master/kernel/sql/database.go"
click node_plugins "https://github.com/siyuan-note/siyuan/blob/master/kernel/plugin/manager.go"
click node_ai_agent "https://github.com/siyuan-note/siyuan/blob/master/kernel/agent/runtime.go"
click node_external "https://github.com/siyuan-note/siyuan/blob/master/kernel/model/cloud_service.go"
click node_docker "https://github.com/siyuan-note/siyuan/blob/master/Dockerfile"
click node_pandoc "https://github.com/siyuan-note/siyuan/tree/master/app/pandoc"

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_electron,node_frontend,node_boot,node_shell,node_editor,node_renderer,node_plugin_ui,node_ai_ui toneBlue
class node_kernel_main,node_server,node_router,node_blocks,node_search_graph,node_docker toneAmber
class node_workspace_model,node_index_db,node_workspace_files toneMint
class node_plugins,node_ai_agent,node_external,node_pandoc toneRose
```

## Components

### Client runtimes

- [Electron host](https://github.com/siyuan-note/siyuan/blob/master/app/electron/main.js): desktop runtime · `app/electron/main.js`
- [Browser frontend](https://github.com/siyuan-note/siyuan/blob/master/app/src/index.ts): TypeScript renderer · `app/src/index.ts`
- [Client boot](https://github.com/siyuan-note/siyuan/blob/master/app/src/boot/onGetConfig.ts): configuration and events · `app/src/boot/onGetConfig.ts`
- [Workspace shell](https://github.com/siyuan-note/siyuan/blob/master/app/src/layout/Model.ts): tabs and layout · `app/src/layout/Model.ts`
- [Protyle editor](https://github.com/siyuan-note/siyuan/blob/master/app/src/protyle/index.ts): block WYSIWYG · `app/src/protyle/index.ts`
- [Rich content renderers](https://github.com/siyuan-note/siyuan/blob/master/app/src/protyle/render/blockRender.ts): math diagram chart PDF · `app/src/protyle/render/blockRender.ts`
- [Plugin frontend API](https://github.com/siyuan-note/siyuan/blob/master/app/src/plugin/API.ts): plugin bridge · `app/src/plugin/API.ts`
- [AI chat UI](https://github.com/siyuan-note/siyuan/blob/master/app/src/ai/chat.ts): streaming chat · `app/src/ai/chat.ts`

### Go kernel

- [Kernel entrypoint](https://github.com/siyuan-note/siyuan/blob/master/kernel/main.go): Go runtime · Also invoked directly by the workspace CLI. · `kernel/main.go`
- [HTTP and WebSocket server](https://github.com/siyuan-note/siyuan/blob/master/kernel/server/serve.go): local API server · `kernel/server/serve.go`
- [API router](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/router.go): request boundary · `kernel/api/router.go`
- [Block transactions](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/transaction.go): document API and model · `kernel/api/transaction.go`
- [Search and graph](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/search.go): indexed knowledge queries · `kernel/api/search.go`
- [Docker service](https://github.com/siyuan-note/siyuan/blob/master/Dockerfile): container delivery · Starts the kernel against a mounted workspace. · `Dockerfile`

### Workspace data

External, mountable user workspace.

- [Document filesystem model](https://github.com/siyuan-note/siyuan/blob/master/kernel/model/filesys_init.go): notebooks and trees · `kernel/model/filesys_init.go`
- [SQL index and queue](https://github.com/siyuan-note/siyuan/blob/master/kernel/sql/database.go): search persistence · `kernel/sql/database.go`
- **Mounted workspace**: documents and assets · Notebook .sy files, assets, templates, storage, and plugins.

### Extensions and integrations

- [Plugin runtime](https://github.com/siyuan-note/siyuan/blob/master/kernel/plugin/manager.go): RPC WebSocket sandbox · `kernel/plugin/manager.go`
- [AI agent runtime](https://github.com/siyuan-note/siyuan/blob/master/kernel/agent/runtime.go): streaming tools · `kernel/agent/runtime.go`
- [External services](https://github.com/siyuan-note/siyuan/blob/master/kernel/model/cloud_service.go): AI sync DAV OCR marketplace MCP · `kernel/model/cloud_service.go`
- [Pandoc export](https://github.com/siyuan-note/siyuan/tree/master/app/pandoc): bundled converter · `app/pandoc`

## Connections

- Electron host → Browser frontend: hosts renderer
- Browser frontend → Client boot: initializes
- Browser frontend → Workspace shell: builds UI
- Workspace shell → Protyle editor: opens documents
- Protyle editor → Rich content renderers: renders blocks
- Browser frontend → API router: HTTP / WebSocket
- Kernel entrypoint → HTTP and WebSocket server: starts
- HTTP and WebSocket server → API router: routes requests
- API router → Block transactions: block APIs
- API router → Search and graph: knowledge queries
- Block transactions → Document filesystem model: reads and writes
- Document filesystem model → Mounted workspace: manages
- Document filesystem model → SQL index and queue: indexes
- Search and graph → SQL index and queue: queries
- API router → Plugin runtime: plugin RPC
- Plugin frontend API → Plugin runtime: frontend bridge
- API router → AI agent runtime: agent API
- AI chat UI → AI agent runtime: streaming chat
- Plugin runtime → External services: marketplace and services
- AI agent runtime → External services: providers and MCP tools
- Kernel entrypoint → Pandoc export: exports through
- Docker service → Kernel entrypoint: runs serve
- Docker service → Mounted workspace: mounts
