Cairn — Architecture Specification¶
The grid goes down. The chart stays up.
Offline-first, vendor-independent electronic health record. Keeps working through any network outage, runs anywhere from a Raspberry Pi to a hospital cluster, and belongs to no vendor.
Status: Architecture / specification phase — no implementation yet. Spec version: 0.9 · License target: AGPL-3.0 (all components AGPL-3.0-compatible). Core constraint: full clinical functionality must survive loss of internet and intranet, degrading gracefully down to a single workstation.
Note
This is the entry point to the multi-file architecture spec. Read this page, then follow the document map. The why behind each decision lives in the Decision log (ADRs), not in per-file changelogs.
Why this exists¶
Most clinicians have, at some point, watched a computerized health record make their day slower, their workflow clumsier, or their patients less safe than the paper chart it replaced — and many have watched promising public efforts collapse under conflicting commercial interests, where lock-in was the business model and interoperability the thing quietly sabotaged.
Cairn starts from a different place. It has no vendor in the room. There is no revenue that depends on trapping your data, no proprietary layer you must license, no cloud you are required to trust. Because nothing here is incentivized to keep the hard problems hard, we let one thing — and only one thing — drive every design decision: what actually happens at the point of care, including at 3 a.m. when the network is down.
The mission¶
Build a health record system that:
- Keeps working through any outage. Loss of internet, loss of the hospital intranet, or a single isolated computer — care continues. The clinician can always read the locally relevant record and write new clinical data. Synchronization catches up when connectivity returns.
- Runs anywhere, for anyone. The same software serves a solar-powered clinic on an intermittent mobile connection and a tertiary hospital in a wealthy country. One codebase, scaled by configuration — from a single workstation to a national deployment.
- Belongs to no one but its users. Fully open source under AGPL-3.0, built only on commodity hardware and open standards, with no proprietary dependency and no vendor lock-in at any layer.
- Respects the clinician's time and judgment. No workflow may be slower, harder, or more error-prone than its paper equivalent.
The eventual goal¶
A genuinely free, genuinely portable electronic health record that any health system in the world — from a one-room rural practice to a national network — can adopt, run, inspect, and adapt without asking anyone's permission and without surrendering control of its data. An EHR that earns clinicians' trust by being available, honest, and fast, and that treats patient safety and data sovereignty as architectural guarantees rather than marketing claims.
Important
Paper-parity is the governing law. No clinical workflow may be slower, more difficult, more cognitively demanding, or impossible compared to its paper-record equivalent (sole exclusions: paper capabilities that constitute malfeasance). A workflow that loses to paper is a defect. See Vision §1.2.
Founding principles (the lens for every decision)¶
Everything in the architecture is downstream of these. New design choices are checked against the first four before anything else.
- Append-only + causal ordering — all clinical content is immutable, signed events ordered by Hybrid Logical Clocks; corrections reference originals. Sync becomes safe set union plus a small, explicitly enumerated set of clinically-reasoned merge policies.
- Identity is a claim, never a fact — never merge, always link; never erase, always overlay. Patient UUIDs are immortal; identity is an append-only event stream; every error is repairable by an auditable event with no data loss.
- Paper-parity (governing law) — see the callout above.
- Acknowledged uncertainty — an imprecise near-truth always beats a precise untruth. The system never forces a clinician to commit data they cannot vouch for; uncertainty, imprecision, ranges, and an explicit unknown (distinct from not-yet-asked and from refused) are first-class recordable values, no required field is satisfiable only by fabrication, and certainty is refined later by overlay (data-model §3.7). Corollary: deletion is best-effort and declared, never guaranteed — the strongest honest claim is "to our knowledge, we have erased all copies in our existence" (data-model §3.8, ADR-0005).
- Availability over consistency — a clinician must always be able to read locally-relevant records and write new data during a partition (AP in CAP terms).
- Fractal topology — one codebase at every tier; a node's role is configuration, not a different product.
- Vendor independence — AGPL-3.0 throughout, open standards, commodity hardware, PostgreSQL; no proprietary services, no mandatory cloud, no license keys.
- Safety-critical logic is unbreakable and auditable — implemented where whole error classes become unrepresentable (Rust or in-database), optimized above all for reviewer-legibility, and kept as small as possible.
- Policy-neutral infrastructure — Cairn provides mechanism, never policy. Conflicting legal and health-system requirements (retention, erasure, disclosure, compliance posture) are facilitated without taking sides: the system builds the full range of mechanisms spanning the worst-case extremes and lets configuration/UI select. The clearest instances are erasure as a policy-selected severity ladder (security §7.1, ADR-0005), confidentiality as a blacklist + grading-system + human-editability the policy/UI combines (identity §5.9, ADR-0006), and compliance posture as configuration (security §7).
Document map¶
| § | Aspect | Document | Covers |
|---|---|---|---|
| 1 | Vision & design goals | vision.md | Goals, the paper-parity test, non-goals, guiding principles |
| 2 | Topology | topology.md | Tiers, write-capability, autonomous nodes vs. thin clients |
| 3 | Data model | data-model.md | Append-only log, UUIDv7/HLC, mutable state, hybrid storage |
| 4 | Demographics | demographics.md | Assertion-stream model, per-field projection policy |
| 5 | Identity subsystem | identity.md | Linkage, matching, registration classes, event algebra, trust states |
| 6 | Synchronisation | sync.md | Mechanism, consistency model, designed-for failure modes |
| 7 | Security & compliance | security.md | Encryption, offline auth, audit, mTLS |
| 8 | Deployment profiles | deployment.md | Hardware floors and stacks per tier |
| 9 | Language & substrate | language-substrate.md | Defect-blast-radius selection rule; the merge boundary |
| 10 | Technology candidates | technology.md | Candidate/reference components and licenses |
| 11 | Open questions | open-questions.md | Remaining brainstorming targets |
| — | Decision log (ADRs) | decisions/ | The why behind settled decisions |
How this spec is organized and versioned¶
- One file per aspect. Each document owns one concern and keeps its section numbering (so cross-references like §5.7 stay valid inside identity.md).
- Git is the line history. Files are not version-suffixed; the spec version is stated here.
- The Decision log is the home of "why." Decisions are recorded as numbered, dated, immutable ADRs; a reversal is a new superseding ADR, never an edit — the project's own "never erase, always overlay" applied to its own documentation. Read the relevant ADR before reopening a settled question.
- Pre-ADR history (the changelogs from v0.1 → v0.6) is preserved verbatim in decisions/0000-pre-adr-changelog-v0.1-v0.6.md.
Reading order¶
- This page (mission + map).
- vision.md — the goals and the paper-parity test that govern everything.
- The aspect documents in order, or jump via the map.
- decisions/ — when you need why a thing is the way it is.
The canonical statements of mission and governance also live in the repository's root
README.md and in Stewardship of the Name. The mission
prose above restates them as the spec's own framing.