Decisions
An Architecture Decision Record (ADR) captures a significant technical decision — the context that motivated it, the decision itself, and its consequences. ADRs are GospeLib's institutional memory: they explain why the system is built the way it is, not just how.
When to Write an ADR
Write an ADR when a decision:
- Affects multiple services or packages (e.g., choosing a database, a communication pattern, or a shared library)
- Is hard to reverse once implemented (e.g., monorepo vs. polyrepo, API versioning strategy)
- Will be questioned later by someone (including future-you) who wasn't in the room
You do not need an ADR for routine implementation choices that stay within a single service and follow established patterns.
ADR Format
Every ADR follows a standard format:
| Section | Purpose |
|---|---|
| Status | Proposed, Accepted, Deprecated, or Superseded |
| Date | When the decision was made |
| Deciders | Who made the decision |
| Context | Why the decision was needed — the forces at play |
| Decision | What was decided |
| Consequences | Positive, negative, and neutral outcomes |
See the full ADR Template for the canonical structure.
How to Propose a New Decision
- Copy the template — duplicate template.md as
docs/adr/NNN-<slug>.mdwith the next sequential number - Set status to
Proposed— fill in every section - Open a PR — the PR description should summarize the decision and tag relevant reviewers
- Discuss in the PR — iterate on context, alternatives, and consequences
- Merge = Accepted — once merged, the status changes to
Acceptedand the ADR is immutable - Create the Docusaurus page — add a corresponding page under
apps/docs/docs/decisions/NNN-<slug>.md
Immutability Rule
ADRs are immutable once accepted. If a decision needs to change:
- Write a new ADR that references and supersedes the old one
- Update the old ADR's status to
Superseded by ADR-NNN - Never edit the original decision text
This preserves the historical reasoning chain — you can always trace why a decision was made and why it was later changed.
Current Decisions
| ADR | Status | Summary |
|---|---|---|
| ADR-001: Monorepo Choice | Accepted | Polyglot monorepo with Nx, pnpm, Go modules, uv |
| ADR-002: ADR Process | Accepted | Adopt Architecture Decision Records for documenting decisions |
| ADR-003: Plugin Permissions | Accepted | Declarative, granular permissions model for community plugins |
| ADR-004: Plugin Sandbox | Accepted | QuickJS WASM sandbox for isolating community plugin code |
Related
- Architecture Overview — how the system is designed
- Service Communication — patterns that stem from architectural decisions