# homielab/noteflare architecture

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

- Interactive diagram: https://gitdiagram.com/homielab/noteflare
- Repository: https://github.com/homielab/noteflare

## Overview

NoteFlare is an end-to-end encrypted notes application, with a React web app, Cloudflare Worker API, and optional SDK/CLI for custom clients. The main workflow is: a visitor passes the app’s access/setup gate, unlocks or creates a vault in the browser, then reads and edits notes in the notebook. The note store and sync engine keep encrypted changes locally and synchronize them through the API; the Worker handles authenticated requests and persistence. Import/export, attachments, offline/PWA support, recovery, and integrations are additional product branches. Some Worker storage details and unsampled feature wiring are only documented, so those links are cited to the README or omitted.

Main entry points: [`src/lib/vault.tsx`](https://github.com/homielab/noteflare/blob/main/src/lib/vault.tsx) (Vault session), [`src/lib/api.ts`](https://github.com/homielab/noteflare/blob/main/src/lib/api.ts) (Web API client), [`worker/index.ts`](https://github.com/homielab/noteflare/blob/main/worker/index.ts) (Worker API), [`src/App.tsx`](https://github.com/homielab/noteflare/blob/main/src/App.tsx) (App gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App gate<br/>[App.tsx]"]
  node_unlock["Unlock screen<br/>[UnlockScreen.tsx]"]
  node_notebook["Notebook<br/>[Notebook.tsx]"]
  node_editor["Note editor<br/>[NoteEditor.tsx]"]
end

subgraph group_vault["Vault and notes"]
  node_vaultctx["Vault session<br/>[vault.tsx]"]
  node_crypto["Encryption<br/>[crypto.ts]"]
  node_notes["Note store<br/>[notes.ts]"]
  node_sync["Sync engine<br/>[engine.ts]"]
  node_local[("Local store<br/>[localStore.ts]")]
end

subgraph group_service["Worker service"]
  node_api["Web API client<br/>[api.ts]"]
  node_worker["Worker API<br/>[index.ts]"]
  node_auth["Access auth<br/>[auth.ts]"]
  node_d1[("D1 database")]
  node_r2[("R2 bucket")]
end

subgraph group_clients["External clients"]
  node_sdk["TypeScript SDK<br/>[client.ts]"]
  node_cli["CLI<br/>[noteflare.mjs]"]
end

subgraph group_support["Offline and features"]
  node_import["Note import<br/>[importMarkdown.ts]"]
  node_attachments["Attachments<br/>[attachments.tsx]"]
  node_pwa["PWA support<br/>[pwa.ts]"]
  node_serviceworker["Offline worker<br/>[sw.js]"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens"| node_app
node_app -->|"provides session"| node_vaultctx
node_app -->|"gates access"| node_unlock
node_app -->|"loads when unlocked"| node_notebook
node_unlock -->|"unlocks vault"| node_vaultctx
node_vaultctx -->|"creates and unlocks keys"| node_crypto
node_vaultctx -->|"loads vault record"| node_api
node_vaultctx -->|"caches vault"| node_local
node_notebook -->|"manages notes"| node_notes
node_notebook -->|"opens note"| node_editor
node_editor -->|"updates note"| node_notes
node_notes -->|"delegates sync"| node_sync
node_notes -->|"reads and writes"| node_local
node_sync -->|"encrypts and decrypts"| node_crypto
node_sync -->|"queues and caches"| node_local
node_sync -->|"pushes and fetches"| node_api
node_api -->|"sends API requests"| node_worker
node_worker -->|"checks access"| node_auth
node_worker -->|"persists encrypted data"| node_d1
node_import -->|"encrypts imported notes"| node_crypto
node_notebook -->|"offers import"| node_import
node_attachments -->|"encrypts images"| node_crypto
node_attachments -->|"uploads and fetches blobs"| node_api
node_api -.->|"stores encrypted blobs"| node_r2
node_vaultctx -->|"keeps offline copy"| node_pwa
node_pwa -.->|"supports offline app"| node_serviceworker
node_sdk -.->|"uses API"| node_worker
node_cli -.->|"uses API"| node_worker

click node_app "https://github.com/homielab/noteflare/blob/main/src/App.tsx"
click node_unlock "https://github.com/homielab/noteflare/blob/main/src/components/UnlockScreen.tsx"
click node_notebook "https://github.com/homielab/noteflare/blob/main/src/components/Notebook.tsx"
click node_editor "https://github.com/homielab/noteflare/blob/main/src/components/NoteEditor.tsx"
click node_vaultctx "https://github.com/homielab/noteflare/blob/main/src/lib/vault.tsx"
click node_crypto "https://github.com/homielab/noteflare/blob/main/packages/client/src/crypto.ts"
click node_notes "https://github.com/homielab/noteflare/blob/main/src/lib/notes.ts"
click node_sync "https://github.com/homielab/noteflare/blob/main/src/lib/sync/engine.ts"
click node_local "https://github.com/homielab/noteflare/blob/main/src/lib/sync/localStore.ts"
click node_api "https://github.com/homielab/noteflare/blob/main/src/lib/api.ts"
click node_worker "https://github.com/homielab/noteflare/blob/main/worker/index.ts"
click node_auth "https://github.com/homielab/noteflare/blob/main/worker/auth.ts"
click node_import "https://github.com/homielab/noteflare/blob/main/src/lib/importMarkdown.ts"
click node_attachments "https://github.com/homielab/noteflare/blob/main/src/lib/attachments.tsx"
click node_pwa "https://github.com/homielab/noteflare/blob/main/src/lib/pwa.ts"
click node_serviceworker "https://github.com/homielab/noteflare/blob/main/src/sw/sw.js"
click node_sdk "https://github.com/homielab/noteflare/blob/main/packages/client/src/client.ts"
click node_cli "https://github.com/homielab/noteflare/blob/main/packages/cli/bin/noteflare.mjs"

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_unlock,node_notebook,node_editor toneBlue
class node_vaultctx,node_crypto,node_notes,node_sync,node_local toneAmber
class node_api,node_worker,node_auth,node_d1,node_r2 toneMint
class node_sdk,node_cli toneRose
class node_import,node_attachments,node_pwa,node_serviceworker,node_visitor toneIndigo
```

## Components

### Web experience

- [App gate](https://github.com/homielab/noteflare/blob/main/src/App.tsx): `src/App.tsx`
- [Unlock screen](https://github.com/homielab/noteflare/blob/main/src/components/UnlockScreen.tsx): `src/components/UnlockScreen.tsx`
- [Notebook](https://github.com/homielab/noteflare/blob/main/src/components/Notebook.tsx): `src/components/Notebook.tsx`
- [Note editor](https://github.com/homielab/noteflare/blob/main/src/components/NoteEditor.tsx): `src/components/NoteEditor.tsx`

### Vault and notes

- [Vault session](https://github.com/homielab/noteflare/blob/main/src/lib/vault.tsx): `src/lib/vault.tsx`
- [Encryption](https://github.com/homielab/noteflare/blob/main/packages/client/src/crypto.ts): `packages/client/src/crypto.ts`
- [Note store](https://github.com/homielab/noteflare/blob/main/src/lib/notes.ts): `src/lib/notes.ts`
- [Sync engine](https://github.com/homielab/noteflare/blob/main/src/lib/sync/engine.ts): `src/lib/sync/engine.ts`
- [Local store](https://github.com/homielab/noteflare/blob/main/src/lib/sync/localStore.ts): `src/lib/sync/localStore.ts`

### Worker service

- [Web API client](https://github.com/homielab/noteflare/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [Worker API](https://github.com/homielab/noteflare/blob/main/worker/index.ts): `worker/index.ts`
- [Access auth](https://github.com/homielab/noteflare/blob/main/worker/auth.ts): `worker/auth.ts`
- **D1 database**
- **R2 bucket**

### External clients

- [TypeScript SDK](https://github.com/homielab/noteflare/blob/main/packages/client/src/client.ts): `packages/client/src/client.ts`
- [CLI](https://github.com/homielab/noteflare/blob/main/packages/cli/bin/noteflare.mjs): `packages/cli/bin/noteflare.mjs`

### Offline and features

- [Note import](https://github.com/homielab/noteflare/blob/main/src/lib/importMarkdown.ts): `src/lib/importMarkdown.ts`
- [Attachments](https://github.com/homielab/noteflare/blob/main/src/lib/attachments.tsx): `src/lib/attachments.tsx`
- [PWA support](https://github.com/homielab/noteflare/blob/main/src/lib/pwa.ts): `src/lib/pwa.ts`
- [Offline worker](https://github.com/homielab/noteflare/blob/main/src/sw/sw.js): `src/sw/sw.js`

### Other components

- **Visitor**

## Connections

- Visitor → App gate: opens (evidence: `src/App.tsx`)
- App gate → Vault session: provides session (evidence: `src/App.tsx`)
- App gate → Unlock screen: gates access (evidence: `src/App.tsx`)
- App gate → Notebook: loads when unlocked (evidence: `src/App.tsx`)
- Unlock screen → Vault session: unlocks vault (evidence: `src/components/UnlockScreen.tsx`)
- Vault session → Encryption: creates and unlocks keys (evidence: `src/lib/vault.tsx`)
- Vault session → Web API client: loads vault record (evidence: `src/lib/vault.tsx`)
- Vault session → Local store: caches vault (evidence: `src/lib/vault.tsx`)
- Notebook → Note store: manages notes (evidence: `src/components/Notebook.tsx`)
- Notebook → Note editor: opens note (evidence: `src/components/Notebook.tsx`)
- Note editor → Note store: updates note (evidence: `src/components/NoteEditor.tsx`)
- Note store → Sync engine: delegates sync (evidence: `src/lib/notes.ts`)
- Note store → Local store: reads and writes (evidence: `src/lib/notes.ts`)
- Sync engine → Encryption: encrypts and decrypts (evidence: `src/lib/sync/engine.ts`)
- Sync engine → Local store: queues and caches (evidence: `src/lib/sync/engine.ts`)
- Sync engine → Web API client: pushes and fetches (evidence: `src/lib/sync/engine.ts`)
- Web API client → Worker API: sends API requests (evidence: `src/lib/api.ts`)
- Worker API → Access auth: checks access (evidence: `worker/index.ts`)
- Worker API → D1 database: persists encrypted data (evidence: `README.md`)
- Note import → Encryption: encrypts imported notes (evidence: `src/lib/importMarkdown.ts`)
- Notebook → Note import: offers import (evidence: `README.md`)
- Attachments → Encryption: encrypts images (evidence: `src/lib/attachments.tsx`)
- Attachments → Web API client: uploads and fetches blobs (evidence: `src/lib/attachments.tsx`)
- Web API client → R2 bucket: stores encrypted blobs (evidence: `README.md`)
- Vault session → PWA support: keeps offline copy (evidence: `src/lib/vault.tsx`)
- PWA support → Offline worker: supports offline app (evidence: `README.md`)
- TypeScript SDK → Worker API: uses API (evidence: `README.md`)
- CLI → Worker API: uses API (evidence: `README.md`)
