Decision records
Architecture decisions live here as short, numbered records. They exist so that a contributor - or an AI assistant - can tell the difference between "this is how it works" and "this was chosen, and here is what it costs".
Format
Every record has the same four sections:
| Section | Content |
|---|---|
| Status | Proposed, Accepted, Superseded by NNNN, Deprecated |
| Context | the forces at play, without advocacy |
| Decision | one sentence, then what it implies |
| Consequences | what gets easier, what gets harder, what is now forbidden |
A record is immutable once accepted. To change a decision, write a new record that supersedes it; do not edit history.
When to write one
Write a record when a choice:
- is expensive to reverse (wire format, threading model, licence, dependency direction);
- constrains future code (a rule reviewers must enforce);
- would otherwise be rediscovered in every review thread.
Do not write one for naming a private function, choosing a test helper, or anything a Cargo.toml
diff explains better than prose.
Relationship to RFCs
- ADR - a decision that has been made, recorded after the fact.
- RFC - a proposal that needs discussion before it is made. See rfcs/README.md.
An accepted RFC that changes the architecture produces an ADR. The RFC keeps the discussion; the ADR keeps the conclusion.
Index
| # | Decision | Status |
|---|---|---|
| 0001 | Tauri's app model, GPUI's renderer | Accepted |
| 0002 | Rust-only frontend and typed IPC | Accepted |
| 0003 | Capabilities at the real boundary | Accepted |
| 0004 | Main thread belongs to GPUI | Accepted |
| 0005 | Hot reload with state preservation | Superseded by 0008 |
| 0006 | Dual MIT/Apache-2.0 | Accepted |
| 0007 | No styling language in 1.0 | Accepted |
| 0008 | Hot reload mechanism revised after feasibility spike | Accepted |
| 0009 | Toolkits are the application's choice | Accepted |
| 0010 | Typed events, delivered on the main thread | Accepted |
| 0011 | Bundling delegates to tauri-bundler | Accepted |
| 0012 | Release trust: Ed25519 manifests, delegated platform signing | Accepted |
| 0013 | AppImage updates: in-place replacement with a backup receipt | Accepted |
| 0014 | Platform updates use the native installer or bundle swap | Accepted |
| 0015 | Restart through the app executable and a durable journal | Accepted |
| 0016 | Delta patches are base-bound; rollout is deterministic | Accepted |
| 0017 | Linux package elevation is explicit pkexec, never self-root | Accepted |
| 0018 | Package rollback requires an explicit older artifact | Superseded in part by 0021 |
| 0019 | macOS package elevation uses an explicit AppleScript prompt | Accepted |
| 0020 | Notarization uses a keychain profile through notarytool | Accepted |
| 0021 | Opt-in rollback after a failed package apply | Accepted |
| 0022 | Hot reload boundary is a separate crate with a fixed frame | Accepted |
| 0023 | The update journal is a local trust boundary | Accepted |