Architecture decision records belong on the diagram
Arcobay · Architecture documentation · Aug 15 · Updated Aug 15
ADRs fail when they live in a folder nobody opens. Put the decision on the node it changes so onboarding and reviews see why, not just what.
An architecture decision record should live on the diagram node it changes — the API gateway, the queue, the auth provider — so people see why while they look at what.
A docs/adr folder is better than nothing and worse than a map. Six months later nobody searches “ADR-014” when they hover the checkout service. Arcobay stores the decision on the component, with tags, history, and a path into Q&A.
What to write on a node
- The choice (e.g. Postgres over DynamoDB) in one sentence.
- The constraint that forced it (latency, team skill, existing dump).
- A link to the longer RFC if you have one.
That is enough for a client handoff and for a new hire’s first week. See also Arcobay vs Swimm if you currently sync snippets into code comments instead.
FAQ
Replacement for RFCs? No. Keep long RFCs in git. The diagram holds the durable outcome on the component.
Who edits decisions? Members with edit access; last-edited attribution stays on the record.