How naveedharri/baalda works
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.ts HTTP API · App.tsx Desktop app · service.ts MCP service · commands.rs Vault commands
Components 26
Desktop experience
- Desktop app
app/apps/desktop/src/App.tsx - Markdown editor
app/apps/desktop/src/components/Editor.tsx - Search and graph
app/apps/desktop/src/lib/graph/useGraphData.ts - Desktop auth
app/apps/desktop/src/lib/auth/authManager.ts
Local vault
- Desktop IPC
app/apps/desktop/src/lib/ipc.ts - Vault commands
app/apps/desktop/src-tauri/src/commands.rs - Markdown files
- Filesystem watcher
app/apps/desktop/src-tauri/src/watcher.rs - Local search index
app/apps/desktop/src-tauri/src/index.rs - Text extraction
app/apps/desktop/src-tauri/src/extract_worker.rs
Team collaboration
- Note CRDT bridge
app/apps/desktop/src/lib/bridge/noteBridge.ts - Note sync
app/apps/desktop/src/lib/sync/syncManager.ts - Vault sync
app/apps/desktop/src/lib/sync/vaultSyncEngine.ts
Server services
- HTTP API
app/apps/server/src/http/app.ts - Access control
app/apps/server/src/permissions/resolver.ts - Vault registry
app/apps/server/src/registry/tree-ops.ts - Realtime sync server
app/apps/server/src/sync/hocuspocus.ts - CRDT persistence
app/apps/server/src/yjs/persistence.ts - Postgres
app/apps/server/src/db/pool.ts - Attachment storage
app/apps/server/src/blobs/store.ts - Server note index
app/apps/server/src/index/indexer.ts
AI access
- MCP service
app/apps/server/src/mcp/service.ts
Other components
- Person
- Local AI agent
- Cloud AI agent
- Teammate
Connections 32
- 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