How siyuan-note/siyuan works
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: router.go API router · index.ts Browser frontend · filesys_init.go Document filesystem model · main.go Kernel entrypoint
Components 21
Client runtimes
- Electron host
app/electron/main.js - Browser frontend
app/src/index.ts - Client boot
app/src/boot/onGetConfig.ts - Workspace shell
app/src/layout/Model.ts - Protyle editor
app/src/protyle/index.ts - Rich content renderers
app/src/protyle/render/blockRender.ts - Plugin frontend API
app/src/plugin/API.ts - AI chat UI
app/src/ai/chat.ts
Go kernel
- Kernel entrypoint · Also invoked directly by the workspace CLI.
kernel/main.go - HTTP and WebSocket server
kernel/server/serve.go - API router
kernel/api/router.go - Block transactions
kernel/api/transaction.go - Search and graph
kernel/api/search.go - Docker service · Starts the kernel against a mounted workspace.
Dockerfile
Workspace data
External, mountable user workspace.
- Document filesystem model
kernel/model/filesys_init.go - SQL index and queue
kernel/sql/database.go - Mounted workspace · Notebook .sy files, assets, templates, storage, and plugins.
Extensions and integrations
- Plugin runtime
kernel/plugin/manager.go - AI agent runtime
kernel/agent/runtime.go - External services
kernel/model/cloud_service.go - Pandoc export
app/pandoc
Connections 23
- 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