Work in progressUnder active development — not tested as ready for use. Breaking changes land without notice, stored data may need to be discarded between revisions, and there is no auth or security model. These docs describe the intended design as much as the current state.
Architecture Decision Records
Lightweight records of non-obvious decisions. See 0001 for the format and what counts.
| # | Title | Status |
|---|---|---|
| 0001 | Record architecture decisions | Accepted |
| 0002 | Single combined container serves the API and the SPA | Accepted |
| 0003 | Vendor-neutral S3 via Bun's S3 client; drop MinIO and rclone | Accepted |
| 0004 | Bun workspace monorepo; the hook ships as a standalone plugin | Accepted |
| 0005 | Tag-driven image releases | Accepted (CI/registry specifics in 0012) |
| 0006 | Webui consumes shared workspace types directly; no OpenAPI client codegen | Superseded by 0019 |
| 0007 | CouchDB as the primary store | Accepted |
| 0008 | Garage as the S3 object store | Accepted |
| 0009 | Meilisearch for search (Phase 2) | Proposed |
| 0010 | Claude-Code-specific scope (not a generic agent-session logger) | Accepted |
| 0011 | Read CouchDB attachments over HTTP, not nano's attachment.get | Superseded by 0014 |
| 0012 | GitHub Actions + GHCR for releases (pins CI/registry for 0005) | Accepted |
| 0013 | S3 is the transcript's home; the CouchDB attachment is opt-in (supersedes parts of 0011) | Superseded by 0014 |
| 0014 | Transcripts live in S3 only — CouchDB attachment support removed (supersedes 0013) | Accepted |
| 0015 | Tiered architecture (Tier 1 / 2 / 3) | Accepted |
| 0016 | The webapi is the sole I/O gateway and stability column | Accepted |
| 0017 | Hooks and actions are decoupled (many-to-many) | Accepted |
| 0018 | Application/operational logs go to CouchDB (separate database) | Accepted |
| 0019 | OpenAPI spec is the source of truth; clients are generated (supersedes 0006) | Accepted |
| 0020 | Bundled backing services default to no auth | Accepted |
| 0021 | Self-built CouchDB migrations (up/down + views + import/export) | Accepted |
| 0022 | / serves a machine-readable app manifest (agent entrypoint) | Accepted |
| 0023 | Lockstep versioning; components built separately, then combined into one image | Accepted |
| 0024 | Mirror third-party backing-service images to the container registry | Accepted |
| 0025 | Claude Code compatibility is a generated, structured definition | Accepted |
| 0026 | A single main branch | Accepted |
| 0027 | Full-content chunks in CouchDB (per-turn content, not just byte ranges) | Accepted (read + write paths done) |
| 0028 | External vs bundled Meilisearch | Open — undecided |