# jkaplon/trilium architecture

> Architecture diagram of the GitHub repository jkaplon/trilium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jkaplon/trilium
- Repository: https://github.com/jkaplon/trilium

## Overview

##### Main Components

A. Frontend Layer:
- Desktop Application (Electron-based)
- Web Application
- Mobile Frontend
Components should be organized under src/public/app:
- Widgets system (src/public/app/widgets)
- Services (src/public/app/services)
- Type-specific components (src/public/app/widgets/type_widgets)

B. Backend Layer:
- Core Services (src/services)
- API Routes (src/routes/api)
- Database Layer (SQLite, indicated by better-sqlite3 binaries)
- Authentication & Encryption Services
- Sync Service
- Search Engine

C. Data Storage:
- Storage
- Attachment Storage
- Revision History
- Blob Storage

##### Key Relationships to Highlight

A. Data Flow:
- Client-Server Communication (WebSocket + REST API)
- Sync Flow between instances
- Tree Structure
- Encryption/Decryption flow

B. Component Integration:
- Frontend-Backend Communication
- Authentication Flow
- Search & Indexing Pipeline
- Versioning System

##### Architectural Patterns to Emphasize

A. Core Architecture:
**[Desktop/Web/Mobile Client]**
- ↕ HTTP/WS
**[API Layer (ETAPI)]**
- ↕
**[Service Layer]**
- ↕
**[Data Access Layer]**
- ↕
**[SQLite Database]**

B. Note Organization:
**[Note Entity]**
- ↙ ↓ ↘
**[Attributes] [Content] [Attachments]**
- ↓         ↓         ↓
**[Metadata] [Revisions] [Blobs]**

##### Special Features

- Protected Notes System
- Synchronization Mechanism
- Search & Indexing Pipeline
- Sharing/Publishing System
- Scripting Engine Integration

##### Implementation Details to Note

- Database schema relationships
- Security boundaries
- Scalability points
- Sync points between instances
- Plugin/extension points

- Client Layer       |
- [Desktop] [Web] [Mobile]|

- ↕

- API Layer         |
- [REST] [WebSocket] [ETAPI]|

- ↕

- Service Layer       |
- [Notes] [Sync] [Search]|

- ↕

- Data Layer         |
- [SQLite] [Blobs] [Cache]|

Remember to maintain a balance between detail and clarity, focusing on the hierarchical nature of the note-taking system while showing how the various components interact to provide features like synchronization, encryption, and search functionality.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Desktop["Desktop App"]:::frontend
        Web["Web App"]:::frontend
        Mobile["Mobile Frontend"]:::frontend
        
        subgraph FrontendComponents
            Widgets["Widget System"]:::frontend
            TypeWidgets["Type-specific Widgets"]:::frontend
            FrontendServices["Frontend Services"]:::frontend
        end
    end

    subgraph APILayer
        REST["REST API"]:::api
        WS["WebSocket"]:::api
        ETAPI["External API (ETAPI)"]:::api
    end

    subgraph ServiceLayer
        CoreServices["Core Services"]:::service
        AuthService["Authentication"]:::security
        SearchEngine["Search Engine"]:::service
        SyncService["Sync Service"]:::service
        ScriptEngine["Script Engine"]:::service
        ProtectedNotes["Protected Notes"]:::security
        NoteSharing["Note Sharing"]:::service
        ImportExport["Import/Export"]:::service
        BlobService["Blob Service"]:::service
    end

    subgraph DataLayer
        DB[(SQLite Database)]:::storage
        Schema["Database Schema"]:::storage
        Entities["Entity Definitions"]:::storage
        Migrations["DB Migrations"]:::storage
        BlobStorage["Blob Storage"]:::storage
    end

    %% Client Layer Connections
    Desktop & Web & Mobile --> REST
    Desktop & Web & Mobile --> WS

    %% API Layer Connections
    REST & WS & ETAPI --> CoreServices

    %% Service Layer Connections
    CoreServices --> AuthService
    CoreServices --> SearchEngine
    CoreServices --> SyncService
    CoreServices --> ScriptEngine
    CoreServices --> ProtectedNotes
    CoreServices --> NoteSharing
    CoreServices --> ImportExport
    CoreServices --> BlobService

    %% Data Layer Connections
    CoreServices --> DB
    CoreServices --> BlobStorage
    DB --> Schema
    DB --> Entities
    DB --> Migrations

    %% Style Definitions
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef api fill:#e74c3c,stroke:#c0392b,color:white
    classDef service fill:#2ecc71,stroke:#27ae60,color:white
    classDef security fill:#e67e22,stroke:#d35400,color:white
    classDef storage fill:#9b59b6,stroke:#8e44ad,color:white

    %% Click Events
    click Desktop "https://github.com/jkaplon/trilium/tree/master/src/public/app"
    click Widgets "https://github.com/jkaplon/trilium/tree/master/src/public/app/widgets"
    click TypeWidgets "https://github.com/jkaplon/trilium/tree/master/src/public/app/widgets/type_widgets"
    click FrontendServices "https://github.com/jkaplon/trilium/tree/master/src/public/app/services"
    click CoreServices "https://github.com/jkaplon/trilium/tree/master/src/services"
    click REST "https://github.com/jkaplon/trilium/tree/master/src/routes/api"
    click AuthService "https://github.com/jkaplon/trilium/tree/master/src/services/encryption"
    click SearchEngine "https://github.com/jkaplon/trilium/tree/master/src/services/search"
    click SyncService "https://github.com/jkaplon/trilium/blob/master/src/services/sync.js"
    click Schema "https://github.com/jkaplon/trilium/blob/master/db/schema.sql"
    click Entities "https://github.com/jkaplon/trilium/tree/master/src/becca/entities"
    click Migrations "https://github.com/jkaplon/trilium/tree/master/db/migrations"
    click BlobService "https://github.com/jkaplon/trilium/blob/master/src/services/blob.js"
    click ProtectedNotes "https://github.com/jkaplon/trilium/blob/master/src/services/protected_session.js"
    click NoteSharing "https://github.com/jkaplon/trilium/tree/master/src/share"
    click ScriptEngine "https://github.com/jkaplon/trilium/blob/master/src/services/script.js"
    click ImportExport "https://github.com/jkaplon/trilium/tree/master/src/services/import"
    click WS "https://github.com/jkaplon/trilium/blob/master/src/services/ws.js"
    click ETAPI "https://github.com/jkaplon/trilium/tree/master/src/etapi"
```
