Architecture Decision Records
An Architecture Decision Record (ADR) captures one significant decision: the context, what was decided, the consequences, the alternatives rejected, and what would make us revisit it. Accepted ADRs are binding on all work. The process is defined in ADR-0001; new ADRs start from 0000-template.md.
Facts about third-party projects (versions, licenses, feature support) were verified on 2026-10-03 against primary sources (package registries, project documentation, standards bodies). Work packages re-verify them when they pin versions.
Status legend
| Status | Meaning |
|---|---|
| Accepted | Binding. |
| Accepted — validation gate | Binding, but a named spike or work package must confirm specific criteria; if they fail, the ADR is amended at the next gate review. |
| Proposed | Not yet binding. Awaiting owner confirmation or evidence. |
| Superseded by ADR-NNNN | Kept for history. |
Index
| ADR | Title | Status |
|---|---|---|
| 0001 | Record architecture decisions | Accepted |
| 0002 | Repository topology, versioning and cross-repository contracts | Accepted |
| 0003 | Licensing and contribution model | Accepted (owner, 2026-10-04); in force since 2026-10-04; amended 2026-10-06 (MIT-0 for the shared contribution tooling) and 2026-10-27 (the orchestrator signs off for the owner) |
| 0004 | Fidelity contract and layout determinism | Accepted |
| 0005 | Integer layout units (BLU) and deterministic math | Accepted |
| 0006 | Rust core and memory-safety policy for untrusted input | Accepted; amended 2026-10-04 (AWS-LC for the server’s TLS) |
| 0007 | Document model: a Word-shaped stream of stories and atoms | Accepted — validated by CORE-004 (2026-10-09), except preserved atoms (not modelled; CORE-101); performance on the conditions of ADR-0008 |
| 0008 | CRDT engine (Loro) and local-first architecture | Accepted — confirmed after the CORE-004 validation gate; amended 2026-10-08 (Loro on three conditions; the native load target; the advisory exceptions for Loro’s dependencies) |
| 0009 | Text stack: shaping, Unicode, line breaking and the Word measurement model | Accepted — validated by CORE-003 (2026-10-12) |
| 0010 | Font strategy and the bundled font library | Accepted |
| 0011 | Rendering pipeline: display lists, reference rasterizer, PDF | Accepted — validated by CORE-003 (2026-10-12); vello_cpu not adopted for interactive rendering |
| 0012 | Engine boundary: JSON message protocol, C ABI and WebAssembly | Accepted; amended 2026-10-08 (a temporary exception for Loro’s randomness and clock) |
| 0013 | Desktop shell: Qt 6 Quick with thin C++ | Accepted — validation gate (DESK-002) open: built and tested automatically 2026-10-12; manual tests on Windows, macOS and Linux deferred (owner, 2026-10-14) |
| 0014 | Web shell: React and TypeScript, engine in a Web Worker | Accepted — validation gate (WEB-002, met in part 2026-10-12; manual passes outstanding); amended 2026-10-12 (WEB-002 results; one Trusted Types policy; integrity of the engine’s files) |
| 0015 | Server: single Rust binary, zero-knowledge relay | Accepted |
| 0016 | End-to-end encryption and identity with MLS | Accepted — validation gate (SRV-002, met 2026-10-07; external review before GA); amended 2026-10-04 (post-quantum encryption from the first release), 2026-10-07 (SRV-002 results and design details) and 2026-10-17 (details in ADR-0029 and ADR-0030) |
| 0017 | Supply-chain and dependency policy | Accepted; amended 2026-10-04 (agent environment; installing Qt for bayan-desktop; what the license allowlist covers; pnpm without Corepack; root certificate data for the server’s TLS), 2026-10-08 (the libFuzzer license for fuzzing), 2026-10-10 (CodeQL for code scanning in CI) and 2026-10-12 (the bayan-core commit that a shell builds from) |
| 0018 | File formats and conversion priorities | Accepted |
| 0019 | Shared UI manifest; Classic and Focus modes | Accepted |
| 0020 | Accessibility is a release gate | Accepted |
| 0021 | Internationalization and localization | Accepted |
| 0022 | Proofing tools: spelling, grammar, hyphenation | Accepted |
| 0023 | Automation, macros and active-content security | Accepted |
| 0024 | Local AI | Accepted |
| 0025 | Quality gates: determinism, fidelity, fuzzing, performance | Accepted |
| 0026 | Release engineering, signing and updates | Accepted |
| 0027 | Documentation tooling | Accepted |
| 0028 | Server TLS: rustls with aws-lc-rs, HTTPS through a reverse proxy | Accepted (owner, 2026-10-04) |
| 0029 | Identity keys, device approval and account recovery | Accepted (owner, 2026-10-17) — validation gate (Phase-3 identity and recovery work package) |
| 0030 | Commit acceptance, departures and group repair | Accepted (owner, 2026-10-17), with its three departures — validation gate (SRV-103 and Phase 3); amended 2026-10-26 (revoked devices when the server’s device list is stale) |