# naveedharri/baalda architecture

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

- Interactive diagram: https://gitdiagram.com/naveedharri/baalda
- Repository: https://github.com/naveedharri/baalda

## Overview

Baalda is a local-first team knowledge app: people edit Markdown files on disk, while a CRDT bridge merges local edits with collaborators’ live changes. The desktop also provides local search, links, attachments, and vault management; the server adds accounts, permissions, sync, and MCP access for cloud agents. The README documents the main data flows; sampled source confirms selected UI, auth, sync, and MCP behavior, so unsampled implementation details are represented only where the tree and README support them.

Main entry points: [`app/apps/server/src/http/app.ts`](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/http/app.ts) (HTTP API), [`app/apps/desktop/src/App.tsx`](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/App.tsx) (Desktop app), [`app/apps/server/src/mcp/service.ts`](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/mcp/service.ts) (MCP service), [`app/apps/desktop/src-tauri/src/commands.rs`](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/commands.rs) (Vault commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_app["Desktop app<br/>[App.tsx]"]
  node_editor["Markdown editor<br/>[Editor.tsx]"]
  node_search["Search and graph<br/>[useGraphData.ts]"]
  node_auth["Desktop auth<br/>[authManager.ts]"]
end

subgraph group_local["Local vault"]
  node_ipc["Desktop IPC<br/>[ipc.ts]"]
  node_rust["Vault commands<br/>[commands.rs]"]
  node_files["Markdown files"]
  node_watcher["Filesystem watcher<br/>[watcher.rs]"]
  node_index[("Local search index<br/>[index.rs]")]
  node_extract["Text extraction<br/>[extract_worker.rs]"]
end

subgraph group_collab["Team collaboration"]
  node_bridge["Note CRDT bridge<br/>[noteBridge.ts]"]
  node_docsync["Note sync<br/>[syncManager.ts]"]
  node_vaultsync["Vault sync<br/>[vaultSyncEngine.ts]"]
end

subgraph group_server["Server services"]
  node_http["HTTP API<br/>[app.ts]"]
  node_permissions["Access control<br/>[resolver.ts]"]
  node_registry["Vault registry<br/>[tree-ops.ts]"]
  node_syncserver["Realtime sync server<br/>[hocuspocus.ts]"]
  node_persistence["CRDT persistence<br/>[persistence.ts]"]
  node_postgres[("Postgres<br/>[pool.ts]")]
  node_blob["Attachment storage<br/>[store.ts]"]
  node_serverindex["Server note index<br/>[indexer.ts]"]
end

subgraph group_ai["AI access"]
  node_mcp["MCP service<br/>[service.ts]"]
end

node_person(("Person"))
node_localagent(("Local AI agent"))
node_cloudagent(("Cloud AI agent"))
node_teammate(("Teammate"))

node_person -->|"uses"| node_app
node_app -->|"opens notes"| node_editor
node_editor -->|"edits CRDT"| node_bridge
node_localagent -->|"edits files"| node_files
node_person -->|"opens vault"| node_files
node_app -->|"invokes"| node_ipc
node_ipc -->|"commands"| node_rust
node_rust -->|"reads and writes"| node_files
node_files -->|"change events"| node_watcher
node_watcher -->|"derives operations"| node_bridge
node_rust -->|"indexes files"| node_index
node_index -->|"queues extraction"| node_extract
node_search -->|"queries locally"| node_ipc
node_bridge -->|"shares Y.Doc"| node_docsync
node_docsync -->|"mints sync token"| node_http
node_docsync -->|"syncs document"| node_syncserver
node_app -->|"starts vault feed"| node_vaultsync
node_vaultsync -->|"requests vault token"| node_http
node_vaultsync -->|"streams updates"| node_syncserver
node_teammate -->|"collaborates"| node_app
node_http -->|"authenticates"| node_auth
node_http -->|"checks access"| node_permissions
node_http -->|"manages vaults"| node_registry
node_syncserver -->|"persists updates"| node_persistence
node_persistence -->|"stores binary updates"| node_postgres
node_http -->|"handles attachments"| node_blob
node_cloudagent -->|"calls tools"| node_mcp
node_http -->|"routes MCP"| node_mcp
node_mcp -->|"checks access"| node_permissions
node_mcp -->|"manages notes"| node_registry
node_mcp -->|"searches notes"| node_serverindex
node_serverindex -->|"uses database"| node_postgres

click node_app "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/App.tsx"
click node_editor "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/components/Editor.tsx"
click node_search "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/graph/useGraphData.ts"
click node_ipc "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/ipc.ts"
click node_rust "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/commands.rs"
click node_watcher "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/watcher.rs"
click node_index "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/index.rs"
click node_extract "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/extract_worker.rs"
click node_bridge "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/bridge/noteBridge.ts"
click node_docsync "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/sync/syncManager.ts"
click node_vaultsync "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/sync/vaultSyncEngine.ts"
click node_auth "https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/auth/authManager.ts"
click node_http "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/http/app.ts"
click node_permissions "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/permissions/resolver.ts"
click node_registry "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/registry/tree-ops.ts"
click node_syncserver "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/sync/hocuspocus.ts"
click node_persistence "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/yjs/persistence.ts"
click node_postgres "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/db/pool.ts"
click node_blob "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/blobs/store.ts"
click node_mcp "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/mcp/service.ts"
click node_serverindex "https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/index/indexer.ts"

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_editor,node_search,node_auth toneBlue
class node_ipc,node_rust,node_files,node_watcher,node_index,node_extract toneAmber
class node_bridge,node_docsync,node_vaultsync toneMint
class node_http,node_permissions,node_registry,node_syncserver,node_persistence,node_postgres,node_blob,node_serverindex toneRose
class node_mcp,node_person,node_localagent,node_cloudagent,node_teammate toneIndigo
```

## Components

### Desktop experience

- [Desktop app](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/App.tsx): `app/apps/desktop/src/App.tsx`
- [Markdown editor](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/components/Editor.tsx): `app/apps/desktop/src/components/Editor.tsx`
- [Search and graph](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/graph/useGraphData.ts): `app/apps/desktop/src/lib/graph/useGraphData.ts`
- [Desktop auth](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/auth/authManager.ts): `app/apps/desktop/src/lib/auth/authManager.ts`

### Local vault

- [Desktop IPC](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/ipc.ts): `app/apps/desktop/src/lib/ipc.ts`
- [Vault commands](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/commands.rs): `app/apps/desktop/src-tauri/src/commands.rs`
- **Markdown files**
- [Filesystem watcher](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/watcher.rs): `app/apps/desktop/src-tauri/src/watcher.rs`
- [Local search index](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/index.rs): `app/apps/desktop/src-tauri/src/index.rs`
- [Text extraction](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src-tauri/src/extract_worker.rs): `app/apps/desktop/src-tauri/src/extract_worker.rs`

### Team collaboration

- [Note CRDT bridge](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/bridge/noteBridge.ts): `app/apps/desktop/src/lib/bridge/noteBridge.ts`
- [Note sync](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/sync/syncManager.ts): `app/apps/desktop/src/lib/sync/syncManager.ts`
- [Vault sync](https://github.com/naveedharri/baalda/blob/main/app/apps/desktop/src/lib/sync/vaultSyncEngine.ts): `app/apps/desktop/src/lib/sync/vaultSyncEngine.ts`

### Server services

- [HTTP API](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/http/app.ts): `app/apps/server/src/http/app.ts`
- [Access control](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/permissions/resolver.ts): `app/apps/server/src/permissions/resolver.ts`
- [Vault registry](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/registry/tree-ops.ts): `app/apps/server/src/registry/tree-ops.ts`
- [Realtime sync server](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/sync/hocuspocus.ts): `app/apps/server/src/sync/hocuspocus.ts`
- [CRDT persistence](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/yjs/persistence.ts): `app/apps/server/src/yjs/persistence.ts`
- [Postgres](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/db/pool.ts): `app/apps/server/src/db/pool.ts`
- [Attachment storage](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/blobs/store.ts): `app/apps/server/src/blobs/store.ts`
- [Server note index](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/index/indexer.ts): `app/apps/server/src/index/indexer.ts`

### AI access

- [MCP service](https://github.com/naveedharri/baalda/blob/main/app/apps/server/src/mcp/service.ts): `app/apps/server/src/mcp/service.ts`

### Other components

- **Person**
- **Local AI agent**
- **Cloud AI agent**
- **Teammate**

## Connections

- Person → Desktop app: uses
- Desktop app → Markdown editor: opens notes
- Markdown editor → Note CRDT bridge: edits CRDT
- Local AI agent → Markdown files: edits files
- Person → Markdown files: opens vault
- Desktop app → Desktop IPC: invokes
- Desktop IPC → Vault commands: commands
- Vault commands → Markdown files: reads and writes
- Markdown files → Filesystem watcher: change events
- Filesystem watcher → Note CRDT bridge: derives operations
- Vault commands → Local search index: indexes files
- Local search index → Text extraction: queues extraction
- Search and graph → Desktop IPC: queries locally
- Note CRDT bridge → Note sync: shares Y.Doc
- Note sync → HTTP API: mints sync token
- Note sync → Realtime sync server: syncs document
- Desktop app → Vault sync: starts vault feed
- Vault sync → HTTP API: requests vault token
- Vault sync → Realtime sync server: streams updates
- Teammate → Desktop app: collaborates
- HTTP API → Desktop auth: authenticates
- HTTP API → Access control: checks access
- HTTP API → Vault registry: manages vaults
- Realtime sync server → CRDT persistence: persists updates
- CRDT persistence → Postgres: stores binary updates
- HTTP API → Attachment storage: handles attachments
- Cloud AI agent → MCP service: calls tools
- HTTP API → MCP service: routes MCP
- MCP service → Access control: checks access
- MCP service → Vault registry: manages notes
- MCP service → Server note index: searches notes
- Server note index → Postgres: uses database