Skip to content

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.

#DecisionAccepted
0001Enum value objects implement FromStr2026-10-10
0002Response enums allow large_enum_variant2026-10-10
0003Unique indexes are partial2026-10-10
0004generate use-case never overwrites and patches routes.rs2026-10-10
0005SQL reserved words are rejected only in --db projects2026-10-10
0006Logging through tracing, not a Logger port2026-10-10
0007Error contract: the code is name, validation is 4222026-10-10
0008Liveness, readiness and graceful shutdown in every project2026-10-10
0009Generated projects pin their toolchain and use edition 20242026-10-10
0010Generated agent rules have a root entry point and are tested2026-10-10
0011Templates own the shape of generated code; types.rs owns the per-field decisions2026-10-11
0012Presentation holds use case ports; routes are tested with mocks2026-10-11
0013Web frontend: React + daisyUI on Bun, structure generated by Puerto, wire types from OpenAPI2026-10-11
0014Entity ids are generated newtypes2026-10-11
0015Repositories return one RepositoryError2026-10-11
0016Lists are offset pages, capped in the domain2026-10-11
0017Runtime crates next to the generator2026-10-12
0018Domain events: unit of work, outbox, pluggable transport2026-10-12
0019Generated code is formatted by cargo fmt2026-10-12
0020Mail: a port per mail, templates in infrastructure, sent from the worker2026-10-12
0021Auth: one Authenticator port, two adapters (OIDC, local sessions)2026-10-12
0022References between entities are typed ids, checked by foreign keys2026-10-13
0023Un crate por contexto y capa en los proyectos generados2026-11-14
0024Lo que genera Puerto, en castellano2026-11-14