Trilium/docs/TECHNICAL_DOCUMENTATION.md

Trilium Notes - Technical Documentation Index

Welcome to the comprehensive technical and architectural documentation for Trilium Notes. This index provides quick access to all technical documentation resources.

📚 Core Architecture Documentation

ARCHITECTURE.md

Main technical architecture document covering the complete system design.

Topics Covered:

• High-level architecture overview
• Monorepo structure and organization
• Core architecture patterns (Becca, Froca, Shaca)
• Entity system and data model
• Widget-based UI architecture
• Frontend and backend architecture
• API architecture (Internal, ETAPI, WebSocket)
• Build system and tooling
• Testing strategy
• Security overview

Audience: Developers, architects, contributors

---

DATABASE.md

Complete database architecture and schema documentation.

Topics Covered:

• SQLite database structure
• Entity tables (notes, branches, attributes, revisions, attachments, blobs)
• System tables (options, entity_changes, sessions)
• Data relationships and integrity
• Database access patterns
• Migrations and versioning
• Performance optimization
• Backup and maintenance
• Security considerations

Audience: Backend developers, database administrators

---

SYNCHRONIZATION.md

Detailed synchronization protocol and implementation.

Topics Covered:

• Sync architecture overview
• Entity change tracking
• Sync protocol (handshake, pull, push)
• Conflict resolution strategies
• Protected notes synchronization
• Performance optimizations
• Error handling and retry logic
• Sync server configuration
• WebSocket real-time updates
• Troubleshooting guide

Audience: Advanced users, sync server administrators, contributors

---

SCRIPTING.md

Comprehensive guide to the Trilium scripting system.

Topics Covered:

• Script types (frontend, backend, render)
• Frontend API reference
• Backend API reference
• Entity classes (FNote, BNote, etc.)
• Script examples and patterns
• Script storage and execution
• Security considerations
• Performance optimization
• Debugging techniques
• Advanced topics

Audience: Power users, script developers, plugin creators

---

SECURITY_ARCHITECTURE.md

In-depth security architecture and implementation.

Topics Covered:

• Security principles and threat model
• Authentication methods (password, TOTP, OpenID)
• Session management
• Authorization and protected sessions
• Encryption (notes, transport, backups)
• Input sanitization (XSS, SQL injection, CSRF)
• Network security (HTTPS, headers, rate limiting)
• Data security and secure deletion
• Dependency security
• Security best practices
• Incident response

Audience: Security engineers, administrators, auditors

---

🔧 Developer Documentation

Developer Guide

Collection of developer-focused documentation for contributing to Trilium.

Key Documents:

• Environment Setup - Setting up development environment
• Project Structure - Monorepo organization
• Development and Architecture - Various development topics

Topics Include:

• Local development setup
• Building and deployment
• Adding new note types
• Database schema details
• Internationalization
• Icons and UI customization
• Docker development
• Troubleshooting

Audience: Contributors, developers

---

📖 User Documentation

User Guide

Comprehensive end-user documentation for using Trilium.

Key Sections:

• Installation & Setup
• Basic Concepts and Features
• Note Types
• Advanced Usage
• Synchronization
• Import/Export

Audience: End users, administrators

---

Script API

Complete API reference for user scripting.

Coverage:

• Frontend API methods
• Backend API methods
• Entity properties and methods
• Event handlers
• Utility functions

Audience: Script developers, power users

---

🚀 Quick Start Guides

For Users

1. Installation Guide - Get Trilium running
2. Basic Concepts - Learn the fundamentals
3. Scripting Guide - Extend Trilium with scripts

For Developers

1. Environment Setup - Setup development environment
2. Architecture Overview - Understand the system
3. Contributing Guide - Start contributing

For Administrators

1. Server Installation - Deploy Trilium server
2. Synchronization Setup - Configure sync
3. Security Best Practices - Secure your installation

---

🔍 Documentation by Topic

Architecture & Design

• Overall Architecture
• Monorepo Structure
• Three-Layer Cache System
• Entity System
• Widget-Based UI

Data & Storage

• Database Architecture
• Entity Tables
• Data Relationships
• Blob Storage
• Database Migrations

Synchronization

• Sync Architecture
• Sync Protocol
• Conflict Resolution
• Protected Notes Sync
• WebSocket Sync

Security

• Authentication
• Encryption
• Input Sanitization
• Network Security
• Security Best Practices

Scripting & Extensibility

• Script Types
• Frontend API
• Backend API
• Script Examples
• Custom Widgets

Frontend

• Client Architecture
• Widget System
• Event System
• Froca Cache
• UI Components

Backend

• Server Architecture
• Service Layer
• Route Structure
• Becca Cache
• Middleware

Build & Deploy

• Build System
• Package Manager
• Build Tools
• Docker
• Deployment

Testing

• Testing Strategy
• Test Organization
• E2E Testing

---

📋 Reference Documentation

File Locations

trilium/
├── apps/
│   ├── client/         # Frontend application
│   ├── server/         # Backend server
│   ├── desktop/        # Electron app
│   └── ...
├── packages/
│   ├── commons/        # Shared code
│   ├── ckeditor5/      # Rich text editor
│   └── ...
├── docs/
│   ├── ARCHITECTURE.md           # Main architecture doc
│   ├── DATABASE.md              # Database documentation
│   ├── SYNCHRONIZATION.md       # Sync documentation
│   ├── SCRIPTING.md             # Scripting guide
│   ├── SECURITY_ARCHITECTURE.md # Security documentation
│   ├── Developer Guide/         # Developer docs
│   ├── User Guide/             # User docs
│   └── Script API/             # API reference
└── ...

Key Source Files

• Backend Entry: apps/server/src/main.ts
• Frontend Entry: apps/client/src/desktop.ts / apps/client/src/index.ts
• Becca Cache: apps/server/src/becca/becca.ts
• Froca Cache: apps/client/src/services/froca.ts
• Database Schema: apps/server/src/assets/db/schema.sql
• Backend API: apps/server/src/services/backend_script_api.ts
• Frontend API: apps/client/src/services/frontend_script_api.ts

Important Directories

• Entities: apps/server/src/becca/entities/
• Widgets: apps/client/src/widgets/
• Services: apps/server/src/services/
• Routes: apps/server/src/routes/
• Migrations: apps/server/src/migrations/
• Tests: Various *.spec.ts files throughout

---

🎯 Common Tasks

Understanding the Codebase

1. Read ARCHITECTURE.md for overview
2. Explore Monorepo Structure
3. Review Entity System
4. Check Key Files

Adding Features

1. Review relevant architecture documentation
2. Check Developer Guide
3. Follow existing patterns in codebase
4. Write tests
5. Update documentation

Debugging Issues

1. Check Troubleshooting
2. Review Database for data issues
3. Check Synchronization for sync issues
4. Review Security for auth issues

Performance Optimization

1. Database Performance
2. Cache Optimization
3. Build Optimization
4. Script Performance

---

🔗 External Resources

Official Links

• Website: https://triliumnotes.org
• Documentation: https://docs.triliumnotes.org
• GitHub: https://github.com/TriliumNext/Trilium
• Discussions: https://github.com/TriliumNext/Trilium/discussions
• Matrix Chat: https://matrix.to/#/#triliumnext:matrix.org

Community Resources

• Awesome Trilium: https://github.com/Nriver/awesome-trilium
• TriliumRocks: https://trilium.rocks/
• Wiki: https://triliumnext.github.io/Docs/Wiki/

Related Projects

• TriliumDroid: https://github.com/FliegendeWurst/TriliumDroid
• Web Clipper: Included in main repository

---

📝 Documentation Conventions

Document Structure

• Overview section
• Table of contents
• Main content with headings
• Code examples where relevant
• "See Also" references

Code Examples

// TypeScript examples with comments
const example = 'value'

-- SQL examples with formatting
SELECT * FROM notes WHERE noteId = ?

Cross-References

• Use relative links: [text](path/to/file.md)
• Reference sections: [text](file.md#section)
• External links: Full URLs

Maintenance

• Review on major releases
• Update for architectural changes
• Add examples for new features
• Keep API references current

---

🤝 Contributing to Documentation

What to Document

• New features and APIs
• Architecture changes
• Migration guides
• Performance tips
• Security considerations

How to Contribute

1. Edit markdown files in docs/
2. Follow existing structure and style
3. Include code examples
4. Test links and formatting
5. Submit pull request

Documentation Standards

• Clear, concise language
• Complete code examples
• Proper markdown formatting
• Cross-references to related docs
• Updated version numbers

---

📅 Version Information

• Documentation Version: 0.99.3
• Last Updated: November 2025
• Trilium Version: 0.99.3+
• Next Review: When major architectural changes occur

---

💡 Getting Help

For Users

• User Guide
• GitHub Discussions
• Matrix Chat

For Developers

• Developer Guide
• Architecture Docs
• GitHub Issues

For Contributors

• Contributing Guidelines
• Code of Conduct
• Developer Setup

---

Maintained by: TriliumNext Team
License: AGPL-3.0-only
Repository: https://github.com/TriliumNext/Trilium