# lokus-ai/lokus architecture

> Architecture diagram of the GitHub repository lokus-ai/lokus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lokus-ai/lokus
- Repository: https://github.com/lokus-ai/lokus

## Overview

Lokus is a local-first Markdown note-taking desktop app. A user opens or creates a workspace, then works with Markdown notes through the editor and workspace UI; notes remain ordinary local files. The README also documents organization and extension capabilities, including search, graphs, databases, templates, calendars, plugins, and optional encrypted sync. The graph combines these documented product branches with source-index-supported frontend/backend relationships. Several backend and feature implementations were not sampled, so their internal call paths are not asserted.

Main entry points: [`src/features/workspace/useWorkspaceSession.js`](https://github.com/lokus-ai/lokus/blob/main/src/features/workspace/useWorkspaceSession.js) (Workspace session), [`src/App.jsx`](https://github.com/lokus-ai/lokus/blob/main/src/App.jsx) (Application shell), [`src/editor/components/Editor.jsx`](https://github.com/lokus-ai/lokus/blob/main/src/editor/components/Editor.jsx) (Markdown editor), [`src/core/notes/NoteMutationClient.js`](https://github.com/lokus-ai/lokus/blob/main/src/core/notes/NoteMutationClient.js) (Note mutations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_app["Application shell<br/>[App.jsx]"]
  node_workspace["Workspace session"]
end

subgraph group_notes["Notes and editing"]
  node_filetree["File tree<br/>[FileTreeView.jsx]"]
  node_editor["Markdown editor<br/>[Editor.jsx]"]
  node_note_mutations["Note mutations"]
  node_markdown["Markdown pipeline"]
end

subgraph group_organize["Knowledge organization"]
  node_search["Full-text search<br/>[search-engine.js]"]
  node_graph["Knowledge graph<br/>[graphEngine.js]"]
  node_bases["Database views<br/>[BaseManager.js]"]
  node_base_validation["Base validation<br/>[BaseValidator.js]"]
  node_templates["Templates<br/>[manager.js]"]
  node_calendar_ui["Calendar views<br/>[CalendarView.jsx]"]
end

subgraph group_integrations["Extensions and integrations"]
  node_plugins["Plugin manager<br/>[PluginManager.jsx]"]
  node_plugin_runtime["Plugin host<br/>[host.js]"]
  node_sync["Encrypted cloud sync<br/>[SyncEngine.js]"]
  node_storage["Cloud file storage<br/>[StorageManager.js]"]
end

subgraph group_runtime["Desktop runtime"]
  node_note_engine[("Note engine")]
  node_calendar_v2["Calendar integration"]
  node_calendar_legacy["Calendar sync<br/>[engine.rs]"]
  node_local_files[("Local Markdown files")]
  node_tauri["Tauri runtime<br/>[lib.rs]"]
end

node_user(("Workspace user"))
node_cloud_storage[("Cloud storage<br/>external system")]

node_user -->|"opens workspace"| node_app
node_app -->|"activates workspace"| node_workspace
node_workspace -->|"loads and saves session"| node_tauri
node_workspace -->|"reads note files"| node_local_files
node_user -->|"writes notes"| node_editor
node_editor -->|"renders Markdown"| node_markdown
node_filetree -->|"moves notes"| node_note_mutations
node_note_mutations -.->|"mutates notes"| node_note_engine
node_user -->|"searches notes"| node_search
node_user -->|"explores links"| node_graph
node_user -->|"views databases"| node_bases
node_bases -->|"validates configuration"| node_base_validation
node_user -->|"uses templates"| node_templates
node_user -->|"views calendar"| node_calendar_ui
node_calendar_ui -.->|"loads calendar data"| node_calendar_v2
node_calendar_v2 -->|"uses legacy provider"| node_calendar_legacy
node_user -->|"manages plugins"| node_plugins
node_plugins -->|"loads plugin state"| node_plugin_runtime
node_user -.->|"enables optional sync"| node_sync
node_sync -->|"transfers files"| node_storage
node_storage -->|"reads and writes"| node_cloud_storage

click node_app "https://github.com/lokus-ai/lokus/blob/main/src/App.jsx"
click node_workspace "https://github.com/lokus-ai/lokus/blob/main/src/features/workspace/useWorkspaceSession.js"
click node_filetree "https://github.com/lokus-ai/lokus/blob/main/src/features/file-tree/FileTreeView.jsx"
click node_editor "https://github.com/lokus-ai/lokus/blob/main/src/editor/components/Editor.jsx"
click node_note_mutations "https://github.com/lokus-ai/lokus/blob/main/src/core/notes/NoteMutationClient.js"
click node_note_engine "https://github.com/lokus-ai/lokus/tree/main/src-tauri/src/note_engine"
click node_markdown "https://github.com/lokus-ai/lokus/blob/main/src/core/markdown/lokus-md-pipeline.js"
click node_search "https://github.com/lokus-ai/lokus/blob/main/src/core/search/search-engine.js"
click node_graph "https://github.com/lokus-ai/lokus/blob/main/src/core/graph2/graphEngine.js"
click node_bases "https://github.com/lokus-ai/lokus/blob/main/src/bases/core/BaseManager.js"
click node_base_validation "https://github.com/lokus-ai/lokus/blob/main/src/bases/core/BaseValidator.js"
click node_templates "https://github.com/lokus-ai/lokus/blob/main/src/core/templates/manager.js"
click node_calendar_ui "https://github.com/lokus-ai/lokus/blob/main/src/components/Calendar/CalendarView.jsx"
click node_calendar_v2 "https://github.com/lokus-ai/lokus/tree/main/src-tauri/src/calendar_v2"
click node_calendar_legacy "https://github.com/lokus-ai/lokus/blob/main/src-tauri/src/calendar/sync/engine.rs"
click node_plugins "https://github.com/lokus-ai/lokus/blob/main/src/components/PluginManager.jsx"
click node_plugin_runtime "https://github.com/lokus-ai/lokus/blob/main/src/core/plugin-v3/host.js"
click node_sync "https://github.com/lokus-ai/lokus/blob/main/src/core/sync/SyncEngine.js"
click node_storage "https://github.com/lokus-ai/lokus/blob/main/src/core/sync/StorageManager.js"
click node_tauri "https://github.com/lokus-ai/lokus/blob/main/src-tauri/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_workspace,node_user toneBlue
class node_filetree,node_editor,node_note_mutations,node_markdown,node_cloud_storage toneAmber
class node_search,node_graph,node_bases,node_base_validation,node_templates,node_calendar_ui toneMint
class node_plugins,node_plugin_runtime,node_sync,node_storage toneRose
class node_note_engine,node_calendar_v2,node_calendar_legacy,node_local_files,node_tauri toneIndigo
```

## Components

### App entry

- [Application shell](https://github.com/lokus-ai/lokus/blob/main/src/App.jsx): `src/App.jsx`
- [Workspace session](https://github.com/lokus-ai/lokus/blob/main/src/features/workspace/useWorkspaceSession.js): `src/features/workspace/useWorkspaceSession.js`

### Notes and editing

- [File tree](https://github.com/lokus-ai/lokus/blob/main/src/features/file-tree/FileTreeView.jsx): `src/features/file-tree/FileTreeView.jsx`
- [Markdown editor](https://github.com/lokus-ai/lokus/blob/main/src/editor/components/Editor.jsx): `src/editor/components/Editor.jsx`
- [Note mutations](https://github.com/lokus-ai/lokus/blob/main/src/core/notes/NoteMutationClient.js): `src/core/notes/NoteMutationClient.js`
- [Markdown pipeline](https://github.com/lokus-ai/lokus/blob/main/src/core/markdown/lokus-md-pipeline.js): `src/core/markdown/lokus-md-pipeline.js`

### Knowledge organization

- [Full-text search](https://github.com/lokus-ai/lokus/blob/main/src/core/search/search-engine.js): `src/core/search/search-engine.js`
- [Knowledge graph](https://github.com/lokus-ai/lokus/blob/main/src/core/graph2/graphEngine.js): `src/core/graph2/graphEngine.js`
- [Database views](https://github.com/lokus-ai/lokus/blob/main/src/bases/core/BaseManager.js): `src/bases/core/BaseManager.js`
- [Base validation](https://github.com/lokus-ai/lokus/blob/main/src/bases/core/BaseValidator.js): `src/bases/core/BaseValidator.js`
- [Templates](https://github.com/lokus-ai/lokus/blob/main/src/core/templates/manager.js): `src/core/templates/manager.js`
- [Calendar views](https://github.com/lokus-ai/lokus/blob/main/src/components/Calendar/CalendarView.jsx): `src/components/Calendar/CalendarView.jsx`

### Extensions and integrations

- [Plugin manager](https://github.com/lokus-ai/lokus/blob/main/src/components/PluginManager.jsx): `src/components/PluginManager.jsx`
- [Plugin host](https://github.com/lokus-ai/lokus/blob/main/src/core/plugin-v3/host.js): `src/core/plugin-v3/host.js`
- [Encrypted cloud sync](https://github.com/lokus-ai/lokus/blob/main/src/core/sync/SyncEngine.js): `src/core/sync/SyncEngine.js`
- [Cloud file storage](https://github.com/lokus-ai/lokus/blob/main/src/core/sync/StorageManager.js): `src/core/sync/StorageManager.js`

### Desktop runtime

- [Note engine](https://github.com/lokus-ai/lokus/tree/main/src-tauri/src/note_engine): `src-tauri/src/note_engine`
- [Calendar integration](https://github.com/lokus-ai/lokus/tree/main/src-tauri/src/calendar_v2): `src-tauri/src/calendar_v2`
- [Calendar sync](https://github.com/lokus-ai/lokus/blob/main/src-tauri/src/calendar/sync/engine.rs): `src-tauri/src/calendar/sync/engine.rs`
- **Local Markdown files**
- [Tauri runtime](https://github.com/lokus-ai/lokus/blob/main/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`

### Other components

- **Workspace user**
- **Cloud storage**: external system

## Connections

- Workspace user → Application shell: opens workspace (evidence: `README.md`)
- Application shell → Workspace session: activates workspace (evidence: `src/App.jsx`)
- Workspace session → Tauri runtime: loads and saves session (evidence: `src/features/workspace/useWorkspaceSession.js`)
- Workspace session → Local Markdown files: reads note files (evidence: `src/features/workspace/useWorkspaceSession.js`)
- Workspace user → Markdown editor: writes notes (evidence: `README.md`)
- Markdown editor → Markdown pipeline: renders Markdown (evidence: `README.md`)
- File tree → Note mutations: moves notes
- Note mutations → Note engine: mutates notes
- Workspace user → Full-text search: searches notes (evidence: `README.md`)
- Workspace user → Knowledge graph: explores links (evidence: `README.md`)
- Workspace user → Database views: views databases (evidence: `README.md`)
- Database views → Base validation: validates configuration (evidence: `src/bases/core/BaseManager.js`)
- Workspace user → Templates: uses templates (evidence: `README.md`)
- Workspace user → Calendar views: views calendar (evidence: `README.md`)
- Calendar views → Calendar integration: loads calendar data
- Calendar integration → Calendar sync: uses legacy provider (evidence: `src-tauri/src/calendar_v2/commands.rs`)
- Workspace user → Plugin manager: manages plugins (evidence: `README.md`)
- Plugin manager → Plugin host: loads plugin state (evidence: `src/components/PluginManager.jsx`)
- Workspace user → Encrypted cloud sync: enables optional sync (evidence: `README.md`)
- Encrypted cloud sync → Cloud file storage: transfers files (evidence: `src/core/sync/StorageManager.js`)
- Cloud file storage → Cloud storage: reads and writes (evidence: `src/core/sync/StorageManager.js`)
