# yceachan/lightark architecture

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

- Interactive diagram: https://gitdiagram.com/yceachan/lightark
- Repository: https://github.com/yceachan/lightark

## Overview

Folio is a self-hosted personal document workspace. Users unlock the workbench, browse path-based knowledge bases, and read or edit documents; changes and file operations use the API, with revision checks protecting updates. Separate reader paths cover Markdown, PDF, DOCX, and sandboxed HTML. The README also documents offline caching and drafts, PDF annotations, and ZIP export. The backend is represented as one service because its implementation is concentrated in main.rs; finer internal boundaries are not established by the excerpts.

Main entry points: [`frontend/src/api.ts`](https://github.com/yceachan/lightark/blob/main/frontend/src/api.ts) (API client), [`frontend/src/App.tsx`](https://github.com/yceachan/lightark/blob/main/frontend/src/App.tsx) (Workbench UI), [`frontend/src/markdown.ts`](https://github.com/yceachan/lightark/blob/main/frontend/src/markdown.ts) (Markdown renderer), [`frontend/src/Readers.tsx`](https://github.com/yceachan/lightark/blob/main/frontend/src/Readers.tsx) (Document readers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workbench"]
  node_app["Workbench UI<br/>[App.tsx]"]
  node_client_api["API client<br/>[api.ts]"]
end

subgraph group_reading["Readers"]
  node_markdown["Markdown renderer<br/>[markdown.ts]"]
  node_shiki["Code highlighting<br/>[shiki.ts]"]
  node_slugify["Heading slugs<br/>[slugify.ts]"]
  node_readers["Document readers<br/>[Readers.tsx]"]
end

subgraph group_server["Backend"]
  node_backend["HTTP API service<br/>[main.rs]"]
  node_sqlite[("SQLite database")]
  node_blobs[("File blobs")]
end

subgraph group_offline["Offline"]
  node_service_worker["Offline worker<br/>[sw.ts]"]
  node_indexeddb[("Local drafts")]
  node_browser_cache[("Browser cache")]
end

node_person(("Workspace user"))

node_person -->|"uses"| node_app
node_app -->|"requests"| node_client_api
node_app -->|"renders"| node_readers
node_app -->|"renders"| node_markdown
node_readers -->|"reads files"| node_client_api
node_readers -->|"renders Markdown"| node_markdown
node_markdown -->|"highlights code"| node_shiki
node_markdown -->|"creates anchors"| node_slugify
node_client_api -->|"calls API"| node_backend
node_backend -->|"reads and writes"| node_sqlite
node_backend -->|"stores files"| node_blobs
node_client_api -->|"stores drafts"| node_indexeddb
node_service_worker -.->|"caches resources"| node_browser_cache
node_client_api -->|"clears cached data"| node_browser_cache

click node_app "https://github.com/yceachan/lightark/blob/main/frontend/src/App.tsx"
click node_client_api "https://github.com/yceachan/lightark/blob/main/frontend/src/api.ts"
click node_markdown "https://github.com/yceachan/lightark/blob/main/frontend/src/markdown.ts"
click node_shiki "https://github.com/yceachan/lightark/blob/main/frontend/src/shiki.ts"
click node_slugify "https://github.com/yceachan/lightark/blob/main/frontend/src/slugify.ts"
click node_readers "https://github.com/yceachan/lightark/blob/main/frontend/src/Readers.tsx"
click node_backend "https://github.com/yceachan/lightark/blob/main/backend/src/main.rs"
click node_service_worker "https://github.com/yceachan/lightark/blob/main/frontend/src/sw.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_client_api,node_person toneBlue
class node_markdown,node_shiki,node_slugify,node_readers toneAmber
class node_backend,node_sqlite,node_blobs toneMint
class node_service_worker,node_indexeddb,node_browser_cache toneRose
```

## Components

### Workbench

- [Workbench UI](https://github.com/yceachan/lightark/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/yceachan/lightark/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Readers

- [Markdown renderer](https://github.com/yceachan/lightark/blob/main/frontend/src/markdown.ts): `frontend/src/markdown.ts`
- [Code highlighting](https://github.com/yceachan/lightark/blob/main/frontend/src/shiki.ts): `frontend/src/shiki.ts`
- [Heading slugs](https://github.com/yceachan/lightark/blob/main/frontend/src/slugify.ts): `frontend/src/slugify.ts`
- [Document readers](https://github.com/yceachan/lightark/blob/main/frontend/src/Readers.tsx): `frontend/src/Readers.tsx`

### Backend

- [HTTP API service](https://github.com/yceachan/lightark/blob/main/backend/src/main.rs): `backend/src/main.rs`
- **SQLite database**
- **File blobs**

### Offline

- [Offline worker](https://github.com/yceachan/lightark/blob/main/frontend/src/sw.ts): `frontend/src/sw.ts`
- **Local drafts**
- **Browser cache**

### Other components

- **Workspace user**

## Connections

- Workspace user → Workbench UI: uses (evidence: `README.md`)
- Workbench UI → API client: requests (evidence: `frontend/src/App.tsx`)
- Workbench UI → Document readers: renders (evidence: `frontend/src/App.tsx`)
- Workbench UI → Markdown renderer: renders (evidence: `frontend/src/App.tsx`)
- Document readers → API client: reads files (evidence: `frontend/src/Readers.tsx`)
- Document readers → Markdown renderer: renders Markdown (evidence: `frontend/src/Readers.tsx`)
- Markdown renderer → Code highlighting: highlights code (evidence: `frontend/src/markdown.ts`)
- Markdown renderer → Heading slugs: creates anchors (evidence: `frontend/src/markdown.ts`)
- API client → HTTP API service: calls API (evidence: `frontend/src/api.ts`)
- HTTP API service → SQLite database: reads and writes (evidence: `README.md`)
- HTTP API service → File blobs: stores files (evidence: `README.md`)
- API client → Local drafts: stores drafts (evidence: `frontend/src/api.ts`)
- Offline worker → Browser cache: caches resources
- API client → Browser cache: clears cached data (evidence: `frontend/src/api.ts`)
