Why decisions are written down
The code says what. An architecture decision record says why: the context, the options that were weighed, the one that was taken and what it costs. Puerto keeps one for every decision that is not visible in the code, so that a later session, a person’s or an agent’s, inherits the reason instead of re-deriving it or quietly reverting it.
An accepted ADR is never rewritten. When a decision changes, a new ADR supersedes it, and both
link to each other. These pages are the files in
docs/adr/, published as they are:
in English up to 0022, and in Spanish from 0023 on, like the code Puerto generates.
Where to start
Section titled “Where to start”- 0023: One crate per context and layer is the layout of a generated project, with the measurements behind it.
- 0024: Everything generated is in Spanish is the language rule and its exceptions; the vocabulary is the glossary.
- 0017: Runtime crates next to the generator draws the line between what Puerto generates and what it ships as a dependency, and compares Loco, Pavex, Laravel, Rails and Spring Boot.
- 0018: Domain events is the outbox, the unit of work and the worker.
- 0021: Auth is one port with two adapters, OIDC or local sessions.
- 0010: Generated agent rules are tested
is why
AGENTS.mdcannot drift.