docs(dev): integrate some of the architecture notes

2026-02-01 12:09:20 +01:00 · 2025-11-04 15:51:54 +02:00
parent 579b2ce76e
commit 58ac325634
67 changed files with 1428 additions and 1353 deletions
--- a/Guide/Architecture.md
+++ b/Guide/Architecture.md
@@ -0,0 +1,118 @@
+# Architecture
+Trilium Notes is a hierarchical note-taking application built as a TypeScript monorepo. It supports multiple deployment modes (desktop, server, mobile web) and features advanced capabilities including synchronization, scripting, encryption, and rich content editing.
+
+### Key Characteristics
+
+*   **Monorepo Architecture**: Uses pnpm workspaces for dependency management
+*   **Multi-Platform**: Desktop (Electron), Server (Node.js/Express), and Mobile Web
+*   **TypeScript-First**: Strong typing throughout the codebase
+*   **Plugin-Based**: Extensible architecture for note types and UI components
+*   **Offline-First**: Full functionality without network connectivity
+*   **Synchronization-Ready**: Built-in sync protocol for multi-device usage
+
+### Technology Stack
+
+*   **Runtime**: Node.js (backend), Browser/Electron (frontend)
+*   **Language**: TypeScript, JavaScript
+*   **Database**: SQLite (better-sqlite3)
+*   **Build Tools**: Vite, ESBuild, pnpm
+*   **UI Framework**: Custom widget-based system (vanilla HTML, CSS & JavaScript + jQuery), in the process of converting to React/Preact.
+*   **Rich Text**: CKEditor 5 (customized)
+*   **Code Editing**: CodeMirror 6
+*   **Desktop**: Electron
+*   **Server**: Express.js
+
+## Main architecture
+
+Trilium follows a **client-server architecture** even in desktop mode, where Electron runs both the backend server and frontend client within the same process.
+
+```mermaid
+graph TB
+    subgraph Frontend
+        Widgets[Widgets<br/>System]
+        Froca[Froca<br/>Cache]
+        UIServices[UI<br/>Services]
+    end
+    
+    subgraph Backend["Backend Server"]
+        Express[Express<br/>Routes]
+        Becca[Becca<br/>Cache]
+        ScriptEngine[Script<br/>Engine]
+        Database[(SQLite<br/>Database)]
+    end
+    
+    Widgets -.-> API[WebSocket & REST API]
+    Froca -.-> API
+    UIServices -.-> API
+    API -.-> Express
+    API -.-> Becca
+    API -.-> ScriptEngine
+    Becca --> Database
+    Express --> Database
+    ScriptEngine --> Database
+```
+
+### Deployment Modes
+
+1.  **Desktop Application**
+    *   Electron wrapper running both frontend and backend
+    *   Local SQLite database
+    *   Full offline functionality
+    *   Cross-platform (Windows, macOS, Linux)
+2.  **Server Installation**
+    *   Node.js server exposing web interface
+    *   Multi-user capable
+    *   Can sync with desktop clients
+    *   Docker deployment supported
+3.  **Mobile Web**
+    *   Optimized responsive interface
+    *   Accessed via browser
+    *   Requires server installation
+
+## Monorepo Structure
+
+Trilium uses **pnpm workspaces** to manage its monorepo structure, with apps and packages clearly separated.
+
+```
+trilium/
+├── apps/                    # Runnable applications
+│   ├── client/             # Frontend application (shared by server & desktop)
+│   ├── server/             # Node.js server with web interface
+│   ├── desktop/            # Electron desktop application
+│   ├── web-clipper/        # Browser extension for web content capture
+│   ├── db-compare/         # Database comparison tool
+│   ├── dump-db/            # Database export tool
+│   ├── edit-docs/          # Documentation editing tool
+│   ├── build-docs/         # Documentation build tool
+│   └── website/            # Marketing website
+│
+├── packages/               # Shared libraries
+│   ├── commons/           # Shared interfaces and utilities
+│   ├── ckeditor5/         # Custom rich text editor
+│   ├── codemirror/        # Code editor customizations
+│   ├── highlightjs/       # Syntax highlighting
+│   ├── ckeditor5-admonition/     # CKEditor plugin: admonitions
+│   ├── ckeditor5-footnotes/      # CKEditor plugin: footnotes
+│   ├── ckeditor5-keyboard-marker/# CKEditor plugin: keyboard shortcuts
+│   ├── ckeditor5-math/           # CKEditor plugin: math equations
+│   ├── ckeditor5-mermaid/        # CKEditor plugin: diagrams
+│   ├── express-partial-content/  # HTTP partial content middleware
+│   ├── share-theme/              # Shared note theme
+│   ├── splitjs/                  # Split pane library
+│   └── turndown-plugin-gfm/      # Markdown conversion
+│
+├── docs/                   # Documentation
+├── scripts/                # Build and utility scripts
+└── patches/                # Package patches (via pnpm)
+```
+
+### Package Dependencies
+
+The monorepo uses workspace protocol (`workspace:*`) for internal dependencies:
+
+```
+desktop → client → commons
+server  → client → commons
+client  → ckeditor5, codemirror, highlightjs
+ckeditor5 → ckeditor5-* plugins
+```