Architecture decisions¶
Short records of decisions that were expensive to make and would be expensive to reverse. Each states the forces at the time, what was chosen, what was rejected, and what the choice costs — because a decision without its rejected alternatives is folklore, and the next person will re-litigate it from scratch.
Format: a trimmed MADR. Records are immutable once accepted; a decision that changes gets a new record that supersedes the old one, and the old one stays readable.
| # | Decision | Status |
|---|---|---|
| 0001 | Adopt datapizza-ai as the agent vocabulary |
Accepted |
| 0002 | Unify the agentic loop behind ports | Accepted |
| 0003 | Ship an offline scripted backend in the product | Accepted |
| 0004 | Name the project Dogana | Superseded by 0005 |
| 0005 | Name the project Annona | Accepted |
Writing one¶
Add a record when a decision meets any of these:
- it constrains what the code can become (layering, dependencies, protocols);
- it was contested, or the losing option was reasonable;
- it will look wrong to someone who was not in the room.
Skip one when the choice is local, cheap to reverse, and obvious from the code.