Architectural Decision Records#
Architectural decisions are made throughout a project’s lifetime. As a way of keeping track of these decisions, we record these decisions in Architecture Decision Records (ADRs) listed below.
- 1. Record architecture decisions
- 2. Adopt python-copier-template for project structure
- 3. One process, one SQLite database, one folder of files
- 4. Originals are kept; everything else is derived, versioned or disposable
- 5. Capture never waits: client-minted ids, an offline queue, no LLM on the save path
- 6. A vanilla TypeScript PWA with a size budget and lazy chunks
- 7. Tailscale Serve is the only way in; no login code
- 8. Search is SQLite FTS5 with a shared query syntax; embeddings are deferred
- 9. Claude ingest: Messages API, no tools, one structured call per photo
- 10. Queue error classes: outages pause, charged failures count, spend is capped
- 11. Whiteboards become Excalidraw drawings: model skeletons, human scenes, two sanitisers
- 12. Page kinds with flat fields; due date and priority as typed columns
- 13. The MCP server is part of the app: streamable HTTP, add-only writes
- 14. Page text is Markdown, parsed by a library on both sides
- 15. Images are embedded in the page text;
scrap gcis conservative - 16. Deployment: rootless podman units for one server, a Helm chart for Kubernetes
- 17. Import from a Thoth vault goes through
Storeand is idempotent - 18. Single-server installs listen on a Unix socket, reached only through Tailscale Serve
- 19. Kinds and tags editable over MCP, made safe by metadata revisions
- 20. Text enrichment: Claude tags, summarises and relates text pages, apart from the text
- 21. Ingest on a Claude seat:
claude -pwith a long-lived token - 22. Page text editable over MCP, made safe by text revisions
- 23. Bearer token on /mcp and an identity-header setting
- 24. A settings pane in the top bar, with theme overrides
- 25. The trash and a recent-changes feed over MCP
- 26. Claude appends task boxes to a list of actions
- 27. Claude’s write-ups of boards, apart from the text
- 28. Claude-maintained topic pages
- 29. Store health checks as search filters; outdated write-ups are the owner’s to regenerate
- 30. Fewer MCP tools: recent, todos and revert_text folded away
- 30. The trash is purged after N days
- 31. Search orders results by section on the server
- 32. Pins are an ordinary page of links
- 33. Who made a page, and where a text revision came from, are stored
- 34. Claude can move pages to the trash
- 35. Files are read locally, for search
- 36. A todo’s due date, priority and snooze are in a table of their own
- 37. One baseline schema for 1.0
- 38. File text is sent to Claude on capture, bounded
- 39. Generated content keeps only its current version
- 40. Search greps raw text: a parameter, and a scan
- 41. MCP clients download files under /mcp
- 42. MCP clients add SVG diagrams and files to pages
- 43. Public pages: a static site scrap pushes to
- 44. Claude’s reading in a fold, and Claude’s own images not read
- 45. scrap verifies the login proxy’s Keycloak token
- 46. The database on an emptyDir, replicated with Litestream
For more information on ADRs see this blog by Michael Nygard.