An on-call engineer sees that order events are delayed but cannot tell which service publishes them, who owns the consumer, or where to check safe recovery. A 60-page architecture wiki is no help if those answers are buried or stale; a diagram alone may not explain retries or point to the right runbook.
Direct answer: Minimum viable architecture documentation is not a fixed page count. Keep the smallest linked set that covers system boundaries and ownership, critical constraints, canonical API and event contracts, and significant design decisions. Add a runtime, deployment, or data-flow view only when it answers a critical reader question. Link to operational ownership, monitoring, and runbooks instead of duplicating them. Give every artifact an owner, source of truth, state, and update trigger.
Choose the set by the questions readers need to answer
A useful baseline lets a new engineer orient themselves, a reviewer understand a boundary change, and an incident responder find the owner and recovery instructions. It does not need to describe every class, endpoint, and deployment object.
For many teams, a C4 system-context diagram plus a container diagram is enough to orient developers; the C4 model says those two views are sufficient for most software development teams. Add detail where complexity, risk, or a specific audience justifies it.
Start with system boundaries and ownership
A context view shows the system, its users, and the neighboring systems it exchanges information with. A container view opens the system to show its major applications, services, and data stores. Label important relationships: what crosses the boundary, in which direction, and which team owns each side.
The C4 model’s diagram guidance explains the system-context and container levels. The arc42 context-and-scope section recommends delimiting the system from its communication partners and documenting the external interfaces and data exchanged. A small ownership table can complement the map when an arrow alone cannot answer who is responsible.
Avoid compressing several audiences and levels of detail into one crowded drawing. If the system has many external dependencies, group them by a clear rule and link to focused views. Keep proposed design, intended target, and deployed state distinct; a new diagram version does not prove that code shipped. The guide to architecture diagram drift explains how to label and verify those states.
Write constraints as rules a team can check
Do not put “secure,” “scalable,” or “highly available” on a diagram and treat the word as a requirement. Record the constraint or quality goal that changes a design choice, name its owner, and state what evidence would show whether it is met.
An invariant is a rule that must remain true, such as “replaying an order event must not create a second shipment for the same order.” A quality scenario describes how the system should respond to a condition: for example, what a consumer should do when its event broker is unavailable, how that condition is detected, and what recovery behavior is acceptable. The actual response and limits belong to the system’s owners; do not copy an example as if it were your production policy.
The arc42 quality-requirements guidance recommends making important quality requirements specific and measurable. A compact entry can use this form:
- Condition: What user action, failure, load, or change starts the scenario?
- Required response: What must the system or team do?
- Acceptance measure: What time, error rate, data guarantee, or review evidence is acceptable?
- Owner and evidence: Who verifies it, and which test, metric, or policy is authoritative?
Keep critical security, privacy, reliability, and compatibility constraints near the boundary or contract they affect. A delivery guarantee such as at-least-once processing is a contract detail only when the actual system provides it; it is not a universal property of background jobs.
Link to the canonical API and event contracts
A diagram should identify where a team boundary is, but it should not copy a full schema into a picture. Link to the contract maintained by the team that owns the interface. OpenAPI defines a machine-readable description for HTTP APIs. AsyncAPI describes message-based and event-driven APIs, including channels and messages.
Beside each link, record the producer or provider, consumer teams, authentication or data-classification concerns, version or compatibility policy, and the person or group responsible for changes. For event flows, include delivery, ordering, retry, and replay semantics only when they are defined for that interface. The contract is the place to check exact fields; the architecture view explains why the boundary exists and which other parts depend on it.
Add a runtime or deployment view only for a real risk
A static map cannot explain every important interaction. Add a small sequence or flow view when people need to understand a critical path, a failure mode, a sensitive data route, or the handoff between teams. Keep it representative rather than documenting every possible scenario.
The arc42 runtime-view guidance recommends selecting a few architecturally relevant scenarios, including critical interfaces, errors, and operational behavior. A deployment view is useful when the mapping between software components and infrastructure or environments affects a decision or a production task; arc42’s deployment guidance describes that mapping. A one-service application with a simple hosted setup may need only a link to its deployment source. A distributed system with different production and disaster-recovery environments may need a focused deployment view.
For on-call use, link the service owner, dashboard or alert, and recovery runbook from the architecture index. Keep the operational steps in the runbook that the on-call team updates. The architecture documentation should help a responder reach those steps, not create a second copy that will drift.
Keep an ADR history for significant choices
Use an architecture decision record (ADR) for a choice that affects structure, important quality attributes, dependencies, interfaces, or a decision that would be costly to reverse. Do not create an ADR for every pull request or routine implementation choice.
A compact ADR states its context and constraints, the decision and status, alternatives considered, owner, date, and consequences—including costs or risks. arc42’s decision guidance recommends capturing the rationale for important decisions and avoiding duplicate text. AWS’s ADR process treats accepted records as immutable: when the decision changes, write a new record and mark the old one superseded. Link decisions to the affected map or interface so a reviewer can see where they apply. The decision-ledger guide covers when a diagram’s change history is useful alongside an ADR.
Keep volatile facts in the source that owns them
Manually copying data already maintained in code, API specifications, infrastructure-as-code, a service catalog, or a runbook creates another place that can disagree. Link to those sources and keep only architectural meaning that a reader cannot get from the underlying file: responsibility, purpose, boundaries, constraints, risks, and why a choice was made.
Generate detail only when the generating source and update path are reliable. A generated schema is useful when it reflects the interface consumers actually use; an unowned export is just another stale artifact. If a fact cannot be generated or queried, assign its owner and a review trigger.
Build one useful packet for an order event
Here is a sample order path. Replace each name and behavior with the system you actually operate.
flowchart LR
storefront["Storefront"] --> orders["Orders API"]
orders --> topic[("OrderPlaced event")]
topic --> fulfillment["Fulfillment consumer"]
fulfillment --> carrier["Shipping provider"]
The diagram shows boundaries and direction. It does not, by itself, specify event delivery guarantees, retry policy, deployment location, or what an on-call engineer may safely replay. Put those facts at their authoritative sources and link them from the map:
| Reader question | Record to keep or link |
|---|---|
| Which team publishes the event and owns the consumer? | Context/container map or service catalog, with named owners |
| What fields and compatibility rules does the event use? | The canonical AsyncAPI or schema-registry entry |
| Can a replay create duplicate fulfillment? | A testable invariant plus the consumer’s contract and relevant failure-path view |
| What happens when the consumer is unavailable? | The actual retry/dead-letter policy, monitoring, and on-call runbook |
| Why use an event boundary instead of a direct call? | An ADR with constraints, alternatives, decision status, and consequences |
This packet is deliberately small: each item answers a different question, and the links prevent the map from pretending to be the source of every detail.
Give each artifact an owner and an update trigger
A date can show when someone looked at a page; it cannot show that the page was checked against the right source. DORA’s documentation-quality guidance assesses clarity, findability, and reliability, and says documentation needs active maintenance. It does not prescribe a universal artifact list. Use the following contract to make your own set findable and testable:
| Artifact | Owner | Review trigger | How to check it |
|---|---|---|---|
| Context/container map | System or domain owner | A new service, external dependency, or ownership boundary | Compare named elements and flows with the current system sources |
| Quality rule or constraint | Team accountable for the requirement | A requirement, threat, or failure assumption changes | Link the test, measure, policy, or review that verifies it |
| API or event contract | Provider team | An interface or compatibility change | Check the canonical spec and its validation path |
| Runtime/deployment view and operations links | Service or on-call owner | A critical interaction, failure path, or environment changes | Follow the alert and recovery links as a responder would |
| ADR | Decision owner | A significant choice is accepted or superseded | Check status, consequences, and replacement links |
Test the set with a new engineer: can they identify system scope and ownership, find the contract for a boundary, and explain the reason for one important decision? Test it with an on-call scenario: can a responder reach the correct owner and current recovery instructions without guessing? If either exercise fails, add the missing link or focused view—not a generic overview. For review triggers, see how often architecture diagrams should be updated.
Where Arialine fits
When architecture changes are discussed in Slack, Arialine can keep an editable Mermaid system map beside that conversation. Its root message shows the current board version, and version replies can link back to the Slack messages that supplied the change context. That history helps readers follow why the drawing changed; it is not an ADR, proof of deployment, or replacement for API and event contracts, service ownership, or runbooks. Use it for the map when the team maintains that map in Slack, and link the other records where their owners keep them. See the Slack diagram review workflow.
FAQ
Is one diagram enough for a small system?
It can be, if one view makes the system boundary, important internal parts, external dependencies, and ownership legible. Split it when different readers need different levels of detail or the labels stop being useful.
Should every architecture decision have an ADR?
No. Record decisions that materially shape structure, quality attributes, interfaces, dependencies, or costly-to-reverse choices. A routine code change does not need a separate architecture record.
Do architecture documents replace runbooks?
No. Architecture views explain boundaries, rationale, and selected behaviors. A runbook owns the operational procedure; link it from the service or architecture index so responders can find it.
Does an architecture diagram prove what is deployed?
No. A diagram can represent proposed, target, or deployed state. Label which one it claims to show, then verify deployed-state claims against the deployment or runtime source your team trusts.
Add to my Slack