# litcu/logseq architecture

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

- Interactive diagram: https://gitdiagram.com/litcu/logseq
- Repository: https://github.com/litcu/logseq

## Overview

##### Project Core and Its Purpose
- Logseq is a privacy-focused, open-source knowledge management and collaboration platform.
- It is built using multiple technologies (e.g., Clojure/ClojureScript for the core logic, Electron for desktop, native mobile projects for Android and iOS, and TypeScript/React for some UI packages).
- It supports a plugin ecosystem and integrates various modules (e.g., graph parsing, publishing, database, and whiteboard functions).

##### Break Down the Main Components
a. Frontend/UI Layer:
– Located mainly in the “src/main/frontend” directory.
– Contains a rich set of UI components (editors, pages, dialogs, headers, sidebars, whiteboard components, etc.).
– Submodules include rendering, state management, event handlers, and extensions (e.g., for PDF, markdown, and whiteboard functionality).
– Also look at “packages/ui” which provides an additional, reusable UI library for plugins or modular parts of Logseq.

b. Backend / Core Application Layer:
– “src/electron” contains the Electron main process code. This part handles system-level tasks such as file synchronization, window management, and IPC.
– “src/main” also includes shared modules (such as core logic, plugin API, file sync, and database integration).
– The project uses a datascript-based database (see “src/main/frontend/db” and supporting query and migration files), which is key to storing and retrieving user data.

c. Modular Subsystems ("deps" folder and others):
– “deps/common”, “deps/db”, “deps/graph-parser”, “deps/publishing”, and “deps/shui” represent functional modules that act as libraries or plugins providing specific features. For example:
- Graph-parser: Parses and manages note graphs.
- Publishing: Provides export to various formats.
- Shui: Likely supports custom components or themes.
– These modules communicate with the core application, often through well-defined APIs.

d. Cross-Platform / Mobile Integration:
– The “android” and “ios” directories hold native code for mobile versions.
– They integrate with the main codebase (via capacitor configurations and shared business logic) to ensure consistent functionality on mobile platforms.

e. Plugin Ecosystem and External Libraries:
– “libs” contains a set of libraries (LSPlugin) used to manage and invoke plugin-specific functionality.
– “packages/amplify” and “packages/ui” provide additional frameworks or examples, indicating that extensibility is a first-class concern.
– Integration with external systems (e.g., through isomorphic-git and external plugin APIs) is also part of the system.

f. Additional Modules / Tools:
– “tldraw” directory: Contains integration with a whiteboard-like tool, complete with its own module hierarchy (React components, TypeScript code, build configs) to support spatial canvas interactions.
– Testing and development are handled in “e2e-tests”, “src/test”, and “scripts” directories for build, CI/CD, and version bumping.

##### Relationships and Data Flow
– Represent the interaction between the core database (using Datascript) and the frontend queries (for persisting and retrieving notes and metadata).
– Indicate the plugin system and libraries (“libs” and “packages”) as a separate but integrated layer that extends or customizes the core functionality.
– Include mobile-specific components with connection lines to the shared business logic and cross-platform backend modules.
– If applicable, include CI/CD/workflow elements (GitHub workflows, Dockerfile, and build scripts) as supporting infrastructure elements.

##### Architectural Patterns and Design Principles
– Modular architecture: All parts of the system (UI, backend, mobile, plugins) are separated into well-defined directories and components.
– Loose coupling: The dependency management (through “deps.edn”, “package.json”, etc.) and plugin API imply that modules are loosely coupled.
– Cross-platform support: The codebase implements a multi-platform approach to support desktop (Electron), web, and mobile (Android/iOS) within one repo.
– Separation of concerns: Code is isolated into UI (presentation), core (business logic and database), and infrastructure (file syncing, plugin handling) layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend/UI Layer"
        A["Logseq Frontend"]
        B["Reusable UI Library"]
    end

    subgraph "Backend / Core Application Layer"
        C["Electron Main Process"]
        D["Shared Core Modules"]
    end

    subgraph "Database Integration"
        E["Frontend DB (Datascript)"]
        F["Deps DB"]
    end

    subgraph "Modular Subsystems"
        G["Common Module"]
        H["Graph Parser"]
        I["Publishing Module"]
        J["Shui Module"]
    end

    subgraph "Mobile Integration"
        K["Android"]
        L["iOS"]
    end

    subgraph "Plugin Ecosystem & External Libraries"
        M["Plugin Libraries"]
        N["Amplify Framework"]
    end

    subgraph "Additional Tools"
        O["Whiteboard Integration"]
    end

    subgraph "Testing & Development"
        P["E2E Tests"]
        Q["Unit/Integration Tests"]
        R["Build Scripts"]
    end

    %% Connections between layers
    A -->|"IPC"| C
    A -->|"UI-Events"| D
    C -->|"Controls"| D
    D -->|"Query/Store"| E
    D -->|"Query/Store"| F
    D -->|"Utilizes"| G
    D -->|"GraphParse"| H
    D -->|"Publishes"| I
    D -->|"UI-Customization"| J
    D -->|"PluginAPI"| M
    D -->|"ExternalPlugins"| N
    D -->|"MobileSync"| K
    D -->|"MobileSync"| L
    A -->|"Whiteboard"| O
    D -->|"Testing"| P
    D -->|"Testing"| Q
    D -->|"CI/CD"| R

    %% Click Events
    click A "https://github.com/litcu/logseq/tree/master/src/main/frontend"
    click B "https://github.com/litcu/logseq/tree/master/packages/ui"
    click C "https://github.com/litcu/logseq/tree/master/src/electron"
    click D "https://github.com/litcu/logseq/tree/master/src/main"
    click E "https://github.com/litcu/logseq/tree/master/src/main/frontend/db"
    click F "https://github.com/litcu/logseq/tree/master/deps/db"
    click G "https://github.com/litcu/logseq/tree/master/deps/common"
    click H "https://github.com/litcu/logseq/tree/master/deps/graph-parser"
    click I "https://github.com/litcu/logseq/tree/master/deps/publishing"
    click J "https://github.com/litcu/logseq/tree/master/deps/shui"
    click K "https://github.com/litcu/logseq/tree/master/android"
    click L "https://github.com/litcu/logseq/tree/master/ios"
    click M "https://github.com/litcu/logseq/tree/master/libs"
    click N "https://github.com/litcu/logseq/tree/master/packages/amplify"
    click O "https://github.com/litcu/logseq/tree/master/tldraw"
    click P "https://github.com/litcu/logseq/tree/master/e2e-tests"
    click Q "https://github.com/litcu/logseq/tree/master/src/test"
    click R "https://github.com/litcu/logseq/tree/master/scripts"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef modules fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
    classDef mobile fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef plugins fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;
    classDef tools fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    classDef testing fill:#CCD1D1,stroke:#566573,stroke-width:2px;

    class A,B frontend;
    class C,D backend;
    class E,F database;
    class G,H,I,J modules;
    class K,L mobile;
    class M,N plugins;
    class O tools;
    class P,Q,R testing;
```
