Architecture decisions
Status: target. These records describe the choices behind the refactor plan, made before the code that carries them out; each phase keeps them current.
An architecture decision record is one short page about one choice that could reasonably have gone the other way. It says what was decided and why, so a later contributor can tell a deliberate choice from an accident. It also records what was rejected, so the same question is not reopened without new facts.
Format
Each record fits on one screen and has five parts:
| Part | What it says |
|---|---|
| Status | Proposed, Accepted, or Superseded, with the date. A superseded record links to the one that replaced it |
| Context | The problem, and the facts that bear on it |
| Decision | What Deckard does, in a few sentences |
| Consequences | What follows from the decision, including its costs |
| Alternatives considered | What else was weighed, and why each lost |
A record is not edited to change its decision. A new record supersedes it instead, so the history of the reasoning survives.
Index
| # | Decision | Status |
|---|---|---|
| 0001 | Load page bundles through asWebviewUri, not inline |
Accepted |
| 0002 | Preact 10 in the light DOM | Accepted |
| 0003 | No @vscode-elements/elements |
Accepted |
| 0004 | Hand-written message narrowing, one table, no validation library | Accepted |
| 0005 | Inert JSON for initial state | Accepted |
| 0006 | retainContextWhenHidden only where live editing state exists |
Superseded by 0017 |
| 0007 | A fast unit tier under plain mocha | Accepted |
| 0008 | Architecture docs as a separate folder, not guide pages | Accepted |
| 0009 | Constructor injection into a plain Services object, and result objects |
Accepted |
| 0010 | Feature modules run with Promise.allSettled |
Accepted |
| 0011 | The host bundle ships no third-party code | Accepted: amended by 0015 |
| 0012 | Help renders the guide through VS Code’s markdown.api.render |
Accepted: the Phase 0 check passed |
| 0013 | Exclude globs stay on picomatch |
Accepted: path.matchesGlob failed the check |
| 0014 | Pages render synchronously from one store | Accepted |
| 0015 | Note Markdown is tokenized by markdown-it, not by our own parser |
Accepted: amends 0011 |
| 0016 | Each Preact page loads one bundle of its own | Accepted: open question 3, measured at Search |
| 0017 | retainContextWhenHidden on four pages: the Dashboard, Search, the Task Board, and the Notes Graph |
Accepted: open question 1; supersedes 0006 |