architecture-documentation

Write one decision per ADR with context including real numbers, the decision itself, alternatives with rejection reasons, and consequences naming at least one accepted cost. Number it sequentially, store it in docs/adr/ in the repo, and mark it immutable once accepted.

The C4 model provides four zoom levels: System Context, Container, Component, and Code. Most teams should maintain only Levels 1 and 2, hand-authored as Mermaid text in the repo, and generate lower levels on demand rather than maintaining them.

No, accepted ADRs are immutable. To change a decision, write a new ADR that supersedes the old one and mark the original as Superseded. Editing history destroys the record of what was known when the decision was made.

Generate infrastructure, schema, and dependency diagrams in CI from Terraform state, database schemas, or trace data. Hand-author only Context and Container diagrams as text in the repo, and make updating them part of the pull request definition of done.

Use arc42 when you need a document describing the whole system as it stands, such as for onboarding, audits, or handovers. ADRs capture individual decisions; arc42 sections 1, 3, 4, 5, 8, 9, and 11 carry most of the value.