Architecture (ADRs)
Cairn's architecture is captured as Architecture Decision Records in MADR format. Each records one decision — the context, the options weighed, the choice, and its consequences — and they form a forward-only graph rooted at ADR-0001.
The house stack
| Layer | Choice |
|---|---|
| Backend & CLI | Go — single static binary, self-hostable |
| API | REST/JSON for CRUD, SSE for live webhook & trajectory streams |
| Metadata | PostgreSQL — artifacts, annotations, provenance, access, workspaces |
| Bodies | S3-compatible object storage, content-addressed by SHA-256 |
| Identifiers | short opaque base62 public ids |
| Web | server-rendered Go html/template + HTMX + Alpine.js |
| Agent surface | a Go MCP server, authorized via OAuth 2.1 (PKCE) |
Decision records
| ADR | Decision |
|---|---|
| ADR-0001 | Cairn as an AI-native artifact store — product vision & domain model |
| ADR-0002 | Extensible share-type model with a viewer registry |
| ADR-0003 | Triple-surface parity — web, CLI, and MCP over one core service |
| ADR-0004 | MCP as a first-class surface with OAuth authorization |
| ADR-0005 | Short opaque identifiers and the URL scheme |
| ADR-0006 | Unified annotation layer — reactions & comments with typed anchors |
| ADR-0007 | Provenance, link-based access control, and default expiry |
| ADR-0008 | Storage & content model — blob bodies, metadata, content addressing |
| ADR-0009 | Trajectory capture and the OTel-inspired span model |
| ADR-0010 | Live webhook endpoints and real-time stream capture |
| ADR-0011 | Frontend architecture and the unified app shell |
| ADR-0012 | Backend platform and API shape |
The ADRs are the source of truth; this page indexes them. Read them in the repo at
docs/adrs/.