Skip to content
alpha 0.1.0-alpha.7 is on crates.io. Install the CLI Start here

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:

SectionContent
StatusProposed, Accepted, Superseded by NNNN, Deprecated
Contextthe forces at play, without advocacy
Decisionone sentence, then what it implies
Consequenceswhat 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

#DecisionStatus
0001Tauri's app model, GPUI's rendererAccepted
0002Rust-only frontend and typed IPCAccepted
0003Capabilities at the real boundaryAccepted
0004Main thread belongs to GPUIAccepted
0005Hot reload with state preservationSuperseded by 0008
0006Dual MIT/Apache-2.0Accepted
0007No styling language in 1.0Accepted
0008Hot reload mechanism revised after feasibility spikeAccepted
0009Toolkits are the application's choiceAccepted
0010Typed events, delivered on the main threadAccepted
0011Bundling delegates to tauri-bundlerAccepted
0012Release trust: Ed25519 manifests, delegated platform signingAccepted
0013AppImage updates: in-place replacement with a backup receiptAccepted
0014Platform updates use the native installer or bundle swapAccepted
0015Restart through the app executable and a durable journalAccepted
0016Delta patches are base-bound; rollout is deterministicAccepted
0017Linux package elevation is explicit pkexec, never self-rootAccepted
0018Package rollback requires an explicit older artifactSuperseded in part by 0021
0019macOS package elevation uses an explicit AppleScript promptAccepted
0020Notarization uses a keychain profile through notarytoolAccepted
0021Opt-in rollback after a failed package applyAccepted
0022Hot reload boundary is a separate crate with a fixed frameAccepted
0023The update journal is a local trust boundaryAccepted