Architecture Decision Records
Major architectural decisions in KeenEyes are documented as ADRs. ADRs are living documents, not immutable records — each one describes present-tense reality and is amended in place as the decision evolves, with git and a per-ADR changelog preserving the history.
The header
Every ADR carries a current-state header:
| Field | Meaning |
|---|---|
| Status | Proposed (decision pending) · Accepted (adopted and binding) · Amended (accepted, then materially changed post-acceptance) · Superseded by ADR-NNN (reversed by a newer ADR) · Deprecated (no longer applies, nothing replaced it) |
| Revision | vN — monotonic, always equal to the number of Changelog entries; the top changelog entry's vN must match. Gives every state of a decision a stable handle, e.g. "ADR-007 v3". |
| Implementation | Not started · Partial · Shipped — so an accepted decision can't masquerade as built |
| First accepted | Date of original acceptance; **Last amended:** is appended once the ADR is amended in place |
| Relates to | Related (non-superseding) ADRs and the driving GitHub issues/PRs |
The lifecycle
- Refining an existing decision → amend the ADR in place: edit the body to present-tense reality, bump
Revision, add one Changelog line stating what changed and why. Do not append "Update:" notes to the body, and do not mint a near-duplicate ADR. - A genuinely new decision area → a new ADR. Copy TEMPLATE.md, take the next number, add it to this index and to
docs/toc.yml. - Reversing a decision → a new ADR that supersedes the old one. The old ADR's Status flips to
Superseded by ADR-NNNand both link to each other. ADRs are never deleted.
Section semantics: Context is frozen — it records the forces at play when the decision was made and is never rewritten to match later reality. Decision and Consequences are living — they are amended to stay true. Alternatives Considered is frozen — it's the record that stops decisions being re-litigated.
If a code change invalidates something an ADR says, amend the ADR in the same PR.
Index
| ADR | Title | Status | Implementation |
|---|---|---|---|
| ADR-001 | World Manager Architecture | Amended | Shipped |
| ADR-002 | Complete IWorld Event System | Accepted | Shipped |
| ADR-003 | CommandBuffer Abstraction and Reflection Elimination | Accepted | Shipped |
| ADR-004 | Reflection Elimination for AOT Compatibility | Accepted | Shipped |
| ADR-005 | Graphics and Input Abstraction Layers | Accepted | Shipped |
| ADR-006 | Custom MSBuild SDK for KeenEyes Projects | Accepted | Shipped |
| ADR-007 | Capability-Based Plugin Architecture | Accepted | Shipped |
| ADR-008 | Asset Management Architecture | Accepted | Partial |
| ADR-009 | KESL — KeenEyes Shader Language | Accepted | Partial |
| ADR-010 | Graph Node Editor Architecture | Accepted | Shipped |
| ADR-011 | Unified Scene Model | Accepted | Partial |
| ADR-012 | Editor Plugin Extension Architecture | Accepted | Partial |
| ADR-013 | Dynamic Plugin Loading | Accepted | Partial |
| ADR-014 | Replay Playback Runtime and Editor Integration | Amended | Partial |
| ADR-015 | Component Schema Migrations | Accepted | Partial |
| ADR-016 | Mobile Platform Support (iOS & Android) | Proposed | Not started |