Skip to content
notes.vinhnq.com

Search

System DesignSenior14 min read

Architecture docs part 1: arc42, the C4 model, runtime/deployment views and docs-as-code

Review 11 cards
On this page

Architecture docs series: 1. arc42, C4 and docs-as-code · 2. ADRs, quality requirements and an address component example

Code tells you what a system does, but not what it must achieve (1,500 TPS? p99 under 300 ms?), why it uses PostgreSQL rather than MongoDB, or which risks the team has accepted. Six months later a newcomer either doesn’t dare change anything, or changes it and breaks the very constraint that shaped the design. After this post you’ll know when docs are worth writing, how to frame them with arc42, draw C4 diagrams and keep docs alive with docs-as-code.

Part 2 covers ADRs (recording decisions), quality requirements (turning “fast” and “stable” into numbers), the risk register and a sample solution design for an address component. Per-endpoint API documentation is in Async jobs, Idempotency-Key and API docs.

1. Why (and when) to write architecture docs

Key idea: write docs when what they save outweighs the cost of writing and maintaining them: (Cx − Cy) > Cmd. And only write what the code can’t say by itself.

Four goals: knowledge sharing (onboarding in days, not weeks), teamwork (several teams share one understanding of a service boundary), analysis (check the architecture against the requirements before building), communication (product, security, ops and partners each need a different level of detail).

In the course’s rule, Cx is the cost without docs, Cy the cost with docs, and Cmd the cost of writing and maintaining them. Example: a newcomer spends 3 days asking about the payment flow (Cx); with docs it takes 1 day (Cy). The team hires 6 people a year, saving 12 person-days; writing takes 3 days and updating 2 days a year (Cmd = 5), so it’s worth it. An internal script two people use is not.

2. arc42: a 12-section frame

Key idea: arc42 is an open-source template with 12 sections, which fall into the four groups below.

  • Background (1–3): Introduction and Goals, Constraints, Context and Scope.
  • Solution (4–7): Solution Strategy, Building Block View, Runtime View, Deployment View.
  • Crosscutting and decisions (8–9): Crosscutting Concepts, Architecture Decisions (the ADRs).
  • Quality and risk (10–12): Quality Requirements, Risks and Technical Debts, Glossary.
arc42’s 12 sections: the question each one answers
# Section Answers
1 Introduction and Goals What the system is for, the 3–5 most important quality goals, who the stakeholders are
2 Constraints Things you don’t get to choose: mandated technology, regulation, budget, deadlines
3 Context and Scope The system boundary, which people and systems talk to it (business and technical)
4 Solution Strategy The few fundamental decisions that shape everything else
5 Building Block View Static decomposition: containers, components (C4 levels 2 and 3)
6 Runtime View How the blocks cooperate in each important scenario
7 Deployment View Which infrastructure and environments it runs on
8 Crosscutting Concepts Conventions everywhere: logging, security, error handling, idempotency, i18n
9 Architecture Decisions The ADRs
10 Quality Requirements The quality tree and measurable quality scenarios
11 Risks and Technical Debts Known risks, technical debt, and plans to deal with them
12 Glossary Business and technical terms

3. A trimmed template for everyday use

Key idea: the course template folds arc42 into 7 parts for a solution design. Two things to remember: write down what is out of scope too, and list the tech stack with versions.

  • General ≈ arc42 sections 1–3. Solution design ≈ section 4. System architecture ≈ sections 5–7. ADRs, quality requirements, risks, glossary ≈ sections 9–12.
  • Section 8 (crosscutting) isn’t in the template; I usually add a short part for the error format, idempotency and logging/tracing.
The template’s seven parts and what goes in each
  1. General: introduction; requirements (functional and non-functional); objectives; constraints; context (a context diagram plus a table of related components/systems: name, role, owning team); scope (in scope and out of scope, the latter just as important).
  2. Solution design: a description of the solution; a tech stack table with versions (Java 21, Spring Boot 3.3, PostgreSQL 16…), because “we use Kafka” and “we use Kafka 2.8 with ZooKeeper” are very different operational stories.
  3. System architecture: a logical view in C4 (containers, components); runtime views (one sequence diagram per use case); a deployment view (dev, staging, prod).
  4. ADR table.
  5. Quality requirements table.
  6. Risks & technical debt.
  7. Glossary and change history (who changed what, when and why).

The ADR table should record the weight of each criterion and the revisit conditions, not just the chosen option.

What a good ADR records beyond the chosen option

A good ADR (Architecture Decision Record — a short record of one architectural decision and its reasons) records more than the chosen option. When the decision came from scoring several options, also record the weight of each criterion (latency, cost, time to market) and the revisit conditions (“when load exceeds X”, “when the team has someone to run Kafka”). When the context changes, the next person knows why the old decision made sense and when to change it. How to agree on weights before scoring, and the ideality formula, are in Analysing trade-offs like a senior.

4. The C4 model: four zoom levels

Key idea: C4 (by Simon Brown) draws architecture at four levels, each zooming into part of the one above. Each diagram stays at one level.

Level Name Shows Audience
1 System Context Your system as one box, surrounded by users and external systems Everyone, including non-technical people
2 Container Runnable/deployable units: apps, services, databases, queues, and the protocols between them Developers, ops, architects
3 Component Inside one container: the main modules and their responsibilities That container’s developers
4 Code Classes, tables (UML, ERD) Rarely worth drawing by hand; let the IDE generate it

An onboarding system with an address component (levels 1 and 2 merged into one picture):

flowchart LR
    customer["Customer<br/>(mobile app, web)"]
    ops["Operations staff<br/>(back office)"]
    subgraph platform["Onboarding system"]
        gw["API Gateway<br/>routing, auth"]
        onboarding["Onboarding Service<br/>Java 21, Spring Boot"]
        address["Address Service<br/>normalises, verifies addresses"]
        db[("PostgreSQL<br/>address, profile")]
        bus[["Kafka<br/>address-events"]]
    end
    master["Administrative-area master data<br/>(external system)"]
    ocr["Proof-of-residence reader<br/>(external system)"]
    customer -->|HTTPS/JSON| gw
    ops -->|HTTPS/JSON| gw
    gw --> onboarding
    onboarding -->|REST: create, fetch address| address
    address -->|JDBC| db
    address -->|REST: look up province/district/ward| master
    address -->|REST: extract address from image| ocr
    address -->|publish AddressVerified| bus

A diagram is readable without its author standing next to it when:

  • Every box has a name, technology and responsibility.
  • Every arrow has a label: what it does, over which protocol.
  • There’s a legend (key to the symbols) for shapes and colours.
  • Each diagram sits at one zoom level.

The same conventions apply to whiteboard diagrams in an interview; see the end of Designing a URL shortener.

5. Runtime view: one sequence diagram per use case

Key idea: the building block view shows what exists; the runtime view shows how the pieces cooperate. Draw the failure paths too, because that’s where reviewers find problems.

sequenceDiagram
    participant App as Mobile app
    participant On as Onboarding Service
    participant Ad as Address Service
    participant MD as Master data
    participant DB as PostgreSQL
    App->>On: Submit manually entered address (request_id)
    On->>Ad: POST /v1/addresses
    Ad->>DB: INSERT ... ON CONFLICT (request_id) DO NOTHING
    alt request_id already exists
        Ad-->>On: 200, stored address
    else first time
        Ad->>MD: Check province/district/ward exist and nest correctly
        alt valid
            Ad->>DB: verify_status = VERIFIED, version + 1
            Ad-->>On: 201, VERIFIED
        else invalid or master data timeout
            Ad->>DB: verify_status = FAILED or UNVERIFIED, store reason, attempts + 1
            Ad-->>On: 201, user must fix it or it is re-verified later
        end
    end

The “master data timeout” branch forces a question the happy path hides: store UNVERIFIED and let the user continue (fail-open — on error, let it through) or block onboarding (fail-closed — on error, stop)? That’s a business decision, so it deserves an ADR (see part 2).

6. Deployment view

Key idea: write down what runs in each environment, how many instances, and where they differ, so you know what a staging test proves about prod.

Sample deployment view: dev, staging and production for the Address Service
Dev Staging Production
Address Service 1 pod 2 pods 3–10 pods, HPA on CPU, 2 zones
PostgreSQL Shared container Managed, 1 instance Managed, primary + 1 synchronous standby + 1 read replica
Kafka 1 broker 3 brokers 3 brokers, RF 3, min.insync.replicas=2
Master data Mock (WireMock) Provider sandbox Production endpoint, 800 ms timeout
Data Fake seed Anonymised copy Real

7. Docs-as-code

Key idea: treat documentation like code: Markdown/AsciiDoc in the repo, diagrams as text (Mermaid, PlantUML, Structurizr DSL), reviews through pull requests, and CI that builds a static site and checks for dead links.

Text vs drag-and-drop diagrams: the detailed comparison

Ways to stop docs from going stale:

  • Keep docs/ next to the code; add “update docs if needed” to the PR template.
  • Make an ADR mandatory for architectural changes in the review checklist.
  • Generate the mechanical parts (API spec, ERD) from code.
  • Enforce architecture rules with automated tests (ArchUnit for Java), so the component diagram isn’t just wishful thinking.

Exercises

Exercise 1: A container diagram for your pet project

Task (paraphrased): draw a C4 Container diagram for the homestay booking project (app, API, database, cache, payment gateway).

Solution to exercise 1

Boxes Web app (React), Booking API (Spring Boot), PostgreSQL + PostGIS, Redis (search cache), external systems Payment gateway, Email provider. Labelled arrows: “HTTPS/JSON: search, book”, “JDBC”, “RESP: read/write cache”, “HTTPS redirect + IPN”, “SMTP/API: send confirmations”.

Check: every box has a technology and a responsibility, and there are no classes or tables (those belong to another level).

Remember

  • Explain the (Cx − Cy) > Cmd rule with a worked example.
  • List what belongs in the docs (durable, not derivable from code) and what to leave to the code.
  • Name the four C4 levels, who reads each, and why “C4” doesn’t mean “level 4”.
  • Know why a runtime view needs failure paths and a deployment view must show where staging differs from prod.
  • Name at least three docs-as-code practices that keep docs from going stale.

Interview questions

Junior

What is arc42 and what is it for?

An open-source template for architecture documentation with 12 sections, so that every document shares the same structure.

The 12 sections: goals, constraints, context, solution strategy, building blocks, runtime, deployment, crosscutting concepts, decisions, quality requirements, risks, glossary. You don’t have to fill in every one; the main value is that readers know where to look.

What are the levels of the C4 model?

System Context, Container, Component and Code; each level zooms into part of the one above.

Context: the system as one box with its users and external systems. Container: deployable units such as apps, services, databases, queues. Component: modules inside one container. Code: classes, tables; rarely worth drawing by hand.

Mid

How does a runtime view differ from a building block view?

The building block view is the static structure (what exists, how it depends on what); the runtime view shows how the pieces cooperate in each scenario.

The runtime view is usually a sequence diagram, including error and timeout paths. Many problems (chains of synchronous calls, missing idempotency, fail-open vs fail-closed) only become visible there.

What makes a good architecture diagram?

A reader understands it without the author explaining it.

It stays at one zoom level; every box has a name, technology and responsibility; every arrow is labelled with what it does and over which protocol; there’s a legend for shapes and colours; and your own system is clearly distinguished from external ones.

Senior

How do you keep architecture documentation from going stale?

Docs-as-code: docs and text-based diagrams in the repo, reviewed in the same PR as the code, with only the durable parts written by hand.

  • CI builds the docs and checks links.
  • Hand-write goals, constraints, decisions and quality requirements; generate the mechanical parts (API spec, ERD) from code.
  • Put ADRs and doc updates on the review checklist.
  • Enforce architecture rules with tests (ArchUnit) so the component diagram is executed, not just hoped for.
  • Give docs an owner and a review date.
When should you not write architecture documentation?

When writing and maintaining it costs more than it saves.

For example: an internal script with few users, a throwaway prototype, or anything that changes with every commit and is already clear from the code. Even for small systems, though, a few-line ADR for a hard-to-reverse decision (the database, service boundaries, the money data model) is almost always worth it.

Useful phrases for interviews

  • “Code shows what the system does; the docs capture why, and what it has to achieve.”
  • “I only document what’s durable and can’t be derived from the code; the rest gets generated.”
  • “We follow the arc42 structure loosely, so everyone knows decisions live in section nine.”
  • “Let me start with the context diagram, then zoom into the containers that matter for this change.”
  • “Every arrow on the diagram says what flows over it and which protocol it uses.”
  • “The runtime view includes the timeout path, because that’s where the real design question is.”
  • “The deployment view calls out where staging differs from production, so we know what our load test proves.”
  • “Our diagrams are Mermaid in the repo, so they’re reviewed in the same pull request as the code.”

Notes based on the Advanced Backend course (Ronin Engineer), rewritten in my own words.