Code · thebristolsound/birdbrain

Layer	Technology
Desktop shell	Electron 35 + electron-vite + electron-builder
UI	React 19, Tailwind CSS v4, Zustand, TanStack Router, TanStack Query
Capture server	Hono 4 (HTTP, runs in Electron main process)
Database	better-sqlite3 — synchronous, WAL mode, FTS5
Page serialization	freeze-dry
Language	TypeScript (strict)
Testing	Vitest (unit), Playwright (E2E against real Electron)
Package manager	pnpm

1	birdbrain/
2	├── src/
3	│ ├── main/ # Electron main process
4	│ │ ├── services/
5	│ │ │ ├── captureServer.ts # Hono HTTP server (port 19845)
6	│ │ │ ├── database.ts # SQLite + schema migrations
7	│ │ │ ├── storage.ts # File I/O for capture content
8	│ │ │ ├── export.ts # HTML/PDF report generation
9	│ │ │ ├── hash.ts # SHA-256 integrity
10	│ │ │ └── settings.ts # Persistent user settings
11	│ │ └── ipcHandlers.ts # All IPC handler registrations
12	│ ├── preload/ # contextBridge IPC bridge
13	│ ├── renderer/ # React UI
14	│ │ ├── stores/ # Zustand app store
15	│ │ ├── hooks/ # useCases, useCaptures, useTags, useSearch, …
16	│ │ └── components/ # Feature-organized UI components
17	│ └── shared/
18	│ ├── types.ts # Case, Capture, Tag, Selector, …
19	│ └── ipc.ts # Typed IPC channel definitions
20	├── extension/
21	│ └── src/
22	│ ├── background.ts # Service worker
23	│ ├── content.ts # freeze-dry, selector matching, Shadow-DOM toasts
24	│ └── popup/ # Extension popup UI
25	├── e2e/ # Playwright E2E tests
26	├── tests/ # Vitest unit tests
27	└── docs/ # Technical documentation

1	# Clone the repo
2	git clone https://github.com/thebristolsound/birdbrain.git
3	cd birdbrain
4
5	# Install dependencies (also rebuilds native modules for your Electron version)
6	pnpm install
7
8	# Start the desktop app in dev mode with hot reload
9	pnpm dev

1	pnpm build # Production build
2	pnpm package # Package platform installers (NSIS / DMG / AppImage)
3	pnpm test # Vitest unit tests
4	pnpm test:e2e # Playwright E2E against a built app
5	pnpm test:e2e:debug # Playwright with inspector
6	pnpm lint # ESLint
7	pnpm format # Prettier
8	pnpm rebuild:electron # Rebuild native deps after a Node version upgrade

1	# Build the extension once
2	pnpm build:extension
3
4	# Or keep it rebuilding automatically during development
5	pnpm dev:extension

1	sequenceDiagram
2	participant Ext as Chrome Extension
3	participant Hono as Hono Server<br/>(localhost:19845)
4	participant Hash as SHA-256 Hash
5	participant Disk as Disk (flat files)
6	participant DB as SQLite
7	participant UI as Renderer (React)
8
9	Ext->>Hono: POST /api/captures<br/>{ source: 'manual' \| 'auto' \| 'selector' }
10	Hono->>Hono: Validate + dual-layer URL filter
11	Hono->>Hash: Hash freeze-dried HTML
12	Hash->>Disk: Write content files
13	Hash->>DB: INSERT capture row + hash
14	DB-->>Hono: Row ID
15	Hono->>Hono: Post-capture selector matching
16	Hono-->>UI: IPC event → health dashboard update
17	UI-->>UI: Re-render capture list

Files