Trilium/docs/ARCHITECTURE.md

API Architecture

Build System

Package Manager: pnpm

Why pnpm:

• Fast, disk-efficient
• Strict dependency isolation
• Native monorepo support via workspaces
• Patch package support

Workspace Configuration:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

Build Tools

Vite (Development & Production)

• Fast HMR for development
• Optimized production builds
• Asset handling
• Plugin ecosystem

ESBuild (TypeScript compilation)

• Fast TypeScript transpilation
• Bundling support
• Minification

TypeScript

• Project references for monorepo
• Strict type checking
• Shared tsconfig.base.json

Build Scripts

Root package.json scripts:

{
  "server:start": "pnpm run --filter server dev",
  "server:build": "pnpm run --filter server build",
  "client:build": "pnpm run --filter client build",
  "desktop:build": "pnpm run --filter desktop build",
  "test:all": "pnpm test:parallel && pnpm test:sequential"
}

Build Process

Development:

pnpm install            # Install dependencies
pnpm server:start       # Start dev server (port 8080)
# or
pnpm desktop:start      # Start Electron dev

Production (Server):

pnpm server:build       # Build server + client
node apps/server/dist/main.js

Production (Desktop):

pnpm desktop:build      # Build Electron app
# Creates distributable in apps/desktop/out/make/

Docker:

docker build -t trilium .
docker run -p 8080:8080 trilium

Asset Pipeline

Client Assets:

• Entry: apps/client/src/index.html
• Bundled by Vite
• Output: apps/client/dist/

Server Static:

• Serves client assets in production
• Public directory: apps/server/public/

Desktop:

• Packages client assets
• Electron main process: apps/desktop/src/main.ts
• Electron renderer: loads client app

---

Testing Strategy

Test Organization

Parallel Tests (can run simultaneously):

• Client tests
• Package tests
• E2E tests (isolated databases)

Sequential Tests (shared resources):

• Server tests (shared database)
• CKEditor plugin tests

Test Frameworks

• Vitest - Unit and integration tests
• Playwright - E2E tests
• Happy-DOM - DOM testing environment

Running Tests

pnpm test:all          # All tests
pnpm test:parallel     # Fast parallel tests
pnpm test:sequential   # Sequential tests only
pnpm coverage          # With coverage reports

Test Locations

apps/
├── server/
│   └── src/**/*.spec.ts       # Server tests
├── client/
│   └── src/**/*.spec.ts       # Client tests
└── server-e2e/
    └── tests/**/*.spec.ts     # E2E tests

E2E Testing

Server E2E:

• Tests full REST API
• Tests WebSocket functionality
• Tests sync protocol

Desktop E2E:

• Playwright with Electron
• Tests full desktop app
• Screenshot comparison

---

Security Architecture

Encryption System

Per-Note Encryption:

• Notes can be individually protected
• AES-256 encryption
• Password-derived encryption key (PBKDF2)
• Separate protected session management

Protected Session:

• Time-limited access to protected notes
• Automatic timeout
• Re-authentication required
• Frontend: protected_session.ts
• Backend: protected_session.ts

Authentication

Password Auth:

• PBKDF2 key derivation
• Salt per installation
• Hash verification

OpenID Connect:

• External identity provider support
• OAuth 2.0 flow
• Configurable providers

TOTP (2FA):

• Time-based one-time passwords
• QR code setup
• Backup codes

Authorization

Single-User Model:

• Desktop: single user (owner)
• Server: single user per installation

Share Notes:

• Public access without authentication
• Separate Shaca cache
• Read-only access

CSRF Protection

CSRF Tokens:

• Required for state-changing operations
• Token in header or cookie
• Validation middleware

Input Sanitization

XSS Prevention:

• DOMPurify for HTML sanitization
• CKEditor content filtering
• CSP headers

SQL Injection:

• Parameterized queries only
• Better-sqlite3 prepared statements
• No string concatenation in SQL

Dependency Security

Vulnerability Scanning:

• Renovate bot for updates
• npm audit integration
• Override vulnerable sub-dependencies

---

Related Documentation

User Documentation

• User Guide - End-user features and usage
• Installation Guide
• Basic Concepts

Developer Documentation

• Developer Guide - Development setup
• Environment Setup
• Project Structure
• Adding Note Types
• Database Schema

API Documentation

• Script API - User scripting API
• ETAPI Documentation - External API

Additional Resources

• CLAUDE.md - AI assistant guidance
• README.md - Project overview
• SECURITY.md - Security policy

---

Appendices

Glossary

• Becca: Backend Cache - server-side entity cache
• Froca: Frontend Cache - client-side entity mirror
• Shaca: Share Cache - cache for public shared notes
• ETAPI: External API for third-party integrations
• Protected Note: Encrypted note requiring password
• Clone: Note with multiple parent branches
• Branch: Parent-child relationship between notes
• Attribute: Metadata (label or relation) attached to note
• Blob: Binary large object containing note content

File Naming Conventions

• BEntity - Backend entity (e.g., BNote, BBranch)
• FEntity - Frontend entity (e.g., FNote, FBranch)
• *_widget.ts - Widget classes
• *_service.ts - Service modules
• *.spec.ts - Test files
• XXXX_*.sql - Migration files

Architecture Decision Records

For historical context on major architectural decisions, see:

• Migration to TypeScript monorepo
• Adoption of pnpm workspaces
• CKEditor 5 upgrade
• Entity change tracking system