# hanyang06/cairn architecture

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

- Interactive diagram: https://gitdiagram.com/hanyang06/cairn
- Repository: https://github.com/hanyang06/cairn

## Overview

Cairn is an early-stage, local-first content-addressed object store and desktop workbench. The intended user flow is a workbench interaction through the desktop IPC/sidecar boundary into a transport-independent Python command API and the kernel’s storage engine, which records block data in pack files and authoritative identity/location metadata in a SQLite catalog. The sampled UI chiefly implements a customizable card board; note-domain types are being rebuilt. Retrieval, garbage-collection triggers, search, and networking are not yet complete. Some desktop and event wiring is documented or indexed but not shown in excerpts, so those relationships are omitted or marked unverified.

Main entry points: [`py_src/core/storage/engine.py`](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/engine.py) (Storage engine), [`app/src/pages/workbench/workbench.tsx`](https://github.com/hanyang06/cairn/blob/main/app/src/pages/workbench/workbench.tsx) (Workbench page), [`py_src/core/api.py`](https://github.com/hanyang06/cairn/blob/main/py_src/core/api.py) (Kernel command API), [`py_src/core/init.py`](https://github.com/hanyang06/cairn/blob/main/py_src/core/init.py) (Kernel assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workbench"]
  node_workbench["Workbench page<br/>[workbench.tsx]"]
  node_board["Card board<br/>[board.tsx]"]
  node_boardstate["Board layout<br/>[layout.ts]"]
  node_boardprefs["Board preferences<br/>[storage.ts]"]
  node_cardmodel["Card definitions<br/>[cards.ts]"]
  node_fontprefs["Font handling<br/>[fonts.ts]"]
end

subgraph group_boundary["Desktop boundary"]
  node_ipc["IPC commands<br/>[index.ts]"]
  node_tauri["Tauri host<br/>[lib.rs]"]
  node_sidecar["Python sidecar<br/>[sidecar.py]"]
end

subgraph group_kernel["Kernel services"]
  node_api["Kernel command API<br/>[api.py]"]
  node_kernelinit["Kernel assembly<br/>[init.py]"]
  node_eventbus["Event bus<br/>[bus.py]"]
  node_eventlog["Event logging<br/>[logs.py]"]
  node_eventcatalog["Event catalog<br/>[catalog.py]"]
  node_exceptions["Kernel errors<br/>[exc.py]"]
end

subgraph group_storage["Object storage"]
  node_storageengine["Storage engine<br/>[engine.py]"]
  node_identity["Block identity<br/>[id.py]"]
  node_catalogdb[("SQLite catalog<br/>[engine.py]")]
  node_payload["Payload encoding<br/>[payload.py]"]
  node_indexengine["Block indexes<br/>[index.py]"]
  node_hubpack["Hub and packs<br/>[hub.py]"]
  node_gc["Storage reclamation<br/>[gc.py]"]
  node_storagetypes["Index declarations<br/>[types.py]"]
end

subgraph group_domain["Note domain"]
  node_notecanvas["Canvas model<br/>[canvas.py]"]
  node_noteline["Line model<br/>[line.py]"]
  node_notetypes["Note types"]
end

node_user(("User"))

node_user -->|"interacts with"| node_workbench
node_workbench -->|"renders"| node_board
node_workbench -->|"settles layout"| node_boardstate
node_boardstate -->|"lays out"| node_cardmodel
node_workbench -->|"serializes preferences"| node_boardprefs
node_workbench -->|"normalizes fonts"| node_fontprefs
node_workbench -->|"reads and writes"| node_ipc
node_ipc -.->|"forwards commands"| node_tauri
node_tauri -.->|"launches sidecar"| node_sidecar
node_sidecar -->|"dispatches commands"| node_api
node_api -->|"uses kernel"| node_kernelinit
node_kernelinit -->|"assembles"| node_storageengine
node_kernelinit -->|"creates"| node_eventbus
node_kernelinit -->|"subscribes logger"| node_eventlog
node_eventlog -->|"subscribes to"| node_eventbus
node_eventlog -->|"routes events"| node_eventcatalog
node_api -->|"reads and deletes"| node_storageengine
node_storageengine -->|"uses identities"| node_identity
node_storageengine -->|"records locations"| node_catalogdb
node_storageengine -->|"encodes payloads"| node_payload
node_storageengine -->|"queries indexes"| node_indexengine
node_storageengine -->|"reads and writes slots"| node_hubpack
node_gc -->|"uses storage"| node_storageengine
node_gc -->|"reclaims pack space"| node_hubpack
node_indexengine -->|"reads index blocks"| node_storageengine
node_indexengine -->|"decodes index values"| node_payload
node_notecanvas -->|"uses storage"| node_storageengine
node_notecanvas -->|"declares fields"| node_storagetypes
node_noteline -->|"declares fields"| node_storagetypes
node_noteline -->|"uses IDs"| node_identity
node_notetypes -.->|"uses storage"| node_storageengine
node_sidecar -->|"translates errors"| node_exceptions
node_api -->|"raises command errors"| node_exceptions

click node_workbench "https://github.com/hanyang06/cairn/blob/main/app/src/pages/workbench/workbench.tsx"
click node_board "https://github.com/hanyang06/cairn/blob/main/app/src/composites/board/board.tsx"
click node_boardstate "https://github.com/hanyang06/cairn/blob/main/app/src/board/layout.ts"
click node_boardprefs "https://github.com/hanyang06/cairn/blob/main/app/src/board/storage.ts"
click node_cardmodel "https://github.com/hanyang06/cairn/blob/main/app/src/board/cards.ts"
click node_fontprefs "https://github.com/hanyang06/cairn/blob/main/app/src/board/fonts.ts"
click node_ipc "https://github.com/hanyang06/cairn/blob/main/app/src/ipc/index.ts"
click node_tauri "https://github.com/hanyang06/cairn/blob/main/app/src-tauri/src/lib.rs"
click node_sidecar "https://github.com/hanyang06/cairn/blob/main/py_src/app/sidecar.py"
click node_api "https://github.com/hanyang06/cairn/blob/main/py_src/core/api.py"
click node_kernelinit "https://github.com/hanyang06/cairn/blob/main/py_src/core/init.py"
click node_eventbus "https://github.com/hanyang06/cairn/blob/main/py_src/core/event/bus.py"
click node_eventlog "https://github.com/hanyang06/cairn/blob/main/py_src/core/event/logs.py"
click node_eventcatalog "https://github.com/hanyang06/cairn/blob/main/py_src/core/event/catalog.py"
click node_storageengine "https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/engine.py"
click node_identity "https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/db/id.py"
click node_catalogdb "https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/db/engine.py"
click node_payload "https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/db/payload.py"
click node_indexengine "https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/index/index.py"
click node_hubpack "https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/hub.py"
click node_gc "https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/gc.py"
click node_storagetypes "https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/types.py"
click node_notecanvas "https://github.com/hanyang06/cairn/blob/main/py_src/model/note/types/canvas.py"
click node_noteline "https://github.com/hanyang06/cairn/blob/main/py_src/model/note/types/line.py"
click node_notetypes "https://github.com/hanyang06/cairn/tree/main/py_src/model/note/types"
click node_exceptions "https://github.com/hanyang06/cairn/blob/main/py_src/core/exc.py"

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_workbench,node_board,node_boardstate,node_boardprefs,node_cardmodel,node_fontprefs,node_user toneBlue
class node_ipc,node_tauri,node_sidecar toneAmber
class node_api,node_kernelinit,node_eventbus,node_eventlog,node_eventcatalog,node_exceptions toneMint
class node_storageengine,node_identity,node_catalogdb,node_payload,node_indexengine,node_hubpack,node_gc,node_storagetypes toneRose
class node_notecanvas,node_noteline,node_notetypes toneIndigo
```

## Components

### Desktop workbench

- [Workbench page](https://github.com/hanyang06/cairn/blob/main/app/src/pages/workbench/workbench.tsx): `app/src/pages/workbench/workbench.tsx`
- [Card board](https://github.com/hanyang06/cairn/blob/main/app/src/composites/board/board.tsx): `app/src/composites/board/board.tsx`
- [Board layout](https://github.com/hanyang06/cairn/blob/main/app/src/board/layout.ts): `app/src/board/layout.ts`
- [Board preferences](https://github.com/hanyang06/cairn/blob/main/app/src/board/storage.ts): `app/src/board/storage.ts`
- [Card definitions](https://github.com/hanyang06/cairn/blob/main/app/src/board/cards.ts): `app/src/board/cards.ts`
- [Font handling](https://github.com/hanyang06/cairn/blob/main/app/src/board/fonts.ts): `app/src/board/fonts.ts`

### Desktop boundary

- [IPC commands](https://github.com/hanyang06/cairn/blob/main/app/src/ipc/index.ts): `app/src/ipc/index.ts`
- [Tauri host](https://github.com/hanyang06/cairn/blob/main/app/src-tauri/src/lib.rs): `app/src-tauri/src/lib.rs`
- [Python sidecar](https://github.com/hanyang06/cairn/blob/main/py_src/app/sidecar.py): `py_src/app/sidecar.py`

### Kernel services

- [Kernel command API](https://github.com/hanyang06/cairn/blob/main/py_src/core/api.py): `py_src/core/api.py`
- [Kernel assembly](https://github.com/hanyang06/cairn/blob/main/py_src/core/init.py): `py_src/core/init.py`
- [Event bus](https://github.com/hanyang06/cairn/blob/main/py_src/core/event/bus.py): `py_src/core/event/bus.py`
- [Event logging](https://github.com/hanyang06/cairn/blob/main/py_src/core/event/logs.py): `py_src/core/event/logs.py`
- [Event catalog](https://github.com/hanyang06/cairn/blob/main/py_src/core/event/catalog.py): `py_src/core/event/catalog.py`
- [Kernel errors](https://github.com/hanyang06/cairn/blob/main/py_src/core/exc.py): `py_src/core/exc.py`

### Object storage

- [Storage engine](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/engine.py): `py_src/core/storage/engine.py`
- [Block identity](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/db/id.py): `py_src/core/storage/db/id.py`
- [SQLite catalog](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/db/engine.py): `py_src/core/storage/db/engine.py`
- [Payload encoding](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/db/payload.py): `py_src/core/storage/db/payload.py`
- [Block indexes](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/index/index.py): `py_src/core/storage/index/index.py`
- [Hub and packs](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/hub.py): `py_src/core/storage/hub.py`
- [Storage reclamation](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/gc.py): `py_src/core/storage/gc.py`
- [Index declarations](https://github.com/hanyang06/cairn/blob/main/py_src/core/storage/types.py): `py_src/core/storage/types.py`

### Note domain

- [Canvas model](https://github.com/hanyang06/cairn/blob/main/py_src/model/note/types/canvas.py): `py_src/model/note/types/canvas.py`
- [Line model](https://github.com/hanyang06/cairn/blob/main/py_src/model/note/types/line.py): `py_src/model/note/types/line.py`
- [Note types](https://github.com/hanyang06/cairn/tree/main/py_src/model/note/types): `py_src/model/note/types`

### Other components

- **User**

## Connections

- User → Workbench page: interacts with
- Workbench page → Card board: renders (evidence: `app/src/pages/workbench/workbench.tsx`)
- Workbench page → Board layout: settles layout (evidence: `app/src/pages/workbench/workbench.tsx`)
- Board layout → Card definitions: lays out (evidence: `app/src/board/storage.ts`)
- Workbench page → Board preferences: serializes preferences (evidence: `app/src/pages/workbench/workbench.tsx`)
- Workbench page → Font handling: normalizes fonts (evidence: `app/src/pages/workbench/workbench.tsx`)
- Workbench page → IPC commands: reads and writes (evidence: `app/src/pages/workbench/workbench.tsx`)
- IPC commands → Tauri host: forwards commands
- Tauri host → Python sidecar: launches sidecar
- Python sidecar → Kernel command API: dispatches commands (evidence: `py_src/app/sidecar.py`)
- Kernel command API → Kernel assembly: uses kernel (evidence: `py_src/core/api.py`)
- Kernel assembly → Storage engine: assembles (evidence: `py_src/core/init.py`)
- Kernel assembly → Event bus: creates (evidence: `py_src/core/init.py`)
- Kernel assembly → Event logging: subscribes logger (evidence: `py_src/core/init.py`)
- Event logging → Event bus: subscribes to (evidence: `py_src/core/event/logs.py`)
- Event logging → Event catalog: routes events (evidence: `py_src/core/event/logs.py`)
- Kernel command API → Storage engine: reads and deletes (evidence: `py_src/core/api.py`)
- Storage engine → Block identity: uses identities (evidence: `py_src/core/storage/engine.py`)
- Storage engine → SQLite catalog: records locations (evidence: `py_src/core/storage/engine.py`)
- Storage engine → Payload encoding: encodes payloads (evidence: `py_src/core/storage/engine.py`)
- Storage engine → Block indexes: queries indexes (evidence: `py_src/core/storage/engine.py`)
- Storage engine → Hub and packs: reads and writes slots (evidence: `py_src/core/storage/engine.py`)
- Storage reclamation → Storage engine: uses storage (evidence: `py_src/core/storage/gc.py`)
- Storage reclamation → Hub and packs: reclaims pack space (evidence: `py_src/core/storage/gc.py`)
- Block indexes → Storage engine: reads index blocks (evidence: `py_src/core/storage/index/index.py`)
- Block indexes → Payload encoding: decodes index values (evidence: `py_src/core/storage/index/index.py`)
- Canvas model → Storage engine: uses storage (evidence: `py_src/model/note/types/canvas.py`)
- Canvas model → Index declarations: declares fields (evidence: `py_src/model/note/types/canvas.py`)
- Line model → Index declarations: declares fields (evidence: `py_src/model/note/types/line.py`)
- Line model → Block identity: uses IDs (evidence: `py_src/model/note/types/line.py`)
- Note types → Storage engine: uses storage (evidence: `py_src/model/note/types/canvas.py`)
- Python sidecar → Kernel errors: translates errors (evidence: `py_src/app/sidecar.py`)
- Kernel command API → Kernel errors: raises command errors (evidence: `py_src/core/api.py`)