Architecture Documentation and Communication Questions

Direct answer

I start from the readers, not the diagrams: list who will read the documentation and what question each needs answered, then produce the smallest set of views that answers those questions, with one plain-language overview on top and the precise detail underneath. Architecture documentation fails when it is written for the author.

Step 1: Who are the readers and what do they need?

Step 2: What I produce

1. One-page overview: purpose, scope, an executive summary in plain language, the key quality goals (the qualities the system must have, for example availability, cost), constraints, assumptions and risks. This is the client-facing entry point.
2. Context and container diagrams (C4 is a diagram convention with four zoom levels; level 1, context, shows the system and its neighbours, level 2, container, shows its separately running parts), with legend and labelled arrows.
3. Two or three key flows as sequence diagrams (pictures of who sends what message to whom, in time order, for one scenario; for example "place an order", "recover from a failed payment"), because flows explain behaviour that boxes cannot.
4. Data view: what is stored where, who owns it, what is sensitive.
5. Deployment view: what runs where.
6. Decision records (ADRs, architecture decision records: one-page notes on a single decision) for the important choices: the "why".
7. Operations links: runbooks, dashboards, on-call contacts, and a short glossary.

If the organisation wants a ready structure, arc42 is a free 12-section template for exactly this purpose; I would borrow the sections I need rather than fill all twelve.

Serving both engineers and business readers

Layer the document: summary on top (no jargon, decisions and risks stated as consequences), diagrams in the middle, precise detail (protocols, schemas, capacity) in linked appendices. Each diagram gets a one-sentence caption saying what to notice.

Worked example: patient appointment-booking platform for a clinic group

• Overview (half a page): "Lets patients book, move and cancel appointments online. Highest risks: double-booking and exposure of health data. Assumes a single region for now."
• Context diagram: Patient, Reception Staff, the clinic's existing Scheduling System, SMS provider.
• Container diagram: web app, Booking API, Calendar Sync Worker, database, queue.
• Flow: "Patient books slot", including the case where two people pick the same slot.
• ADR: why the Booking API owns slot allocation instead of the legacy system.

The flow, sketched as the sequence diagram would show it:

Patient      -> Web app:      choose 10:00 slot
Web app      -> Booking API:  reserve(10:00)
Booking API  -> Database:     insert reservation only if slot is free
Database     -> Booking API:  ok | conflict
Booking API  -> Web app:      confirmed | "slot taken, pick another"
Booking API  -> SMS provider: send confirmation (only after ok)

And the plain-language layer for a clinic manager: "Patients can book online. The system never books two people into the same slot; if two try at once, the second is told immediately. Health data is stored encrypted in one region." (Illustrative wording.)

Trade-offs and pitfalls

• One giant document nobody reads: split by reader and link.
• Diagrams without narrative: pictures alone cannot carry rationale or assumptions.
• Documenting everything at equal depth. Go deep where risk and change are concentrated.
• Not stating assumptions: they are the first thing a client or reviewer challenges.

Direct answer

I treat the five minutes as a story with a fixed skeleton: why the system exists, the big picture, one path through it, one or two decisions that shaped it, and what I owned. I deliberately leave out the technology inventory and the edge cases, and I keep a 30-second version in my pocket in case I am cut short. If interrupted, I answer the question directly and then rejoin the story with a signpost.

The five-minute structure (with time budget)

What I leave out

The full list of technologies, every service, the org history, minor features, and code-level detail. If it does not help the listener understand the one request path or the two decisions, it waits for a question.

Adapting when interrupted or cut short

• Interruption with a question: answer it in one or two sentences, say "I will come back to that at the data step if that is useful", and return to the point I left.
• Interviewer clearly wants depth on one area: ask "Would you rather I go deeper on X than finish the overview?" and follow their lead. The overview is a means, not the goal.
• Cut to 90 seconds: I lead with the punchline first (what it was, one design decision, the result) and drop the middle. That is why the 30-second version exists.

Worked example (illustrative script): a photo-import service for an online marketplace

"Sellers upload up to fifty photos per listing, and slow uploads were costing us listings. I owned the redesign. Sellers upload directly to object storage using a temporary signed link, so our servers never carry the image bytes. An upload event lands on a queue; a resize worker produces thumbnails and stores the results; the listing service reads them. Follow one upload: the browser asks the API for a link, uploads, the queue message triggers the worker, the listing shows a placeholder until the thumbnail is ready. Two decisions: I chose eventual thumbnails over blocking the seller, trading a short placeholder for a faster upload; and I chose a queue rather than direct calls so a resize backlog could not take down listing pages. I would add better retry visibility next time. I designed the flow and wrote the worker; the outcome was that upload complaints dropped."

The script above is deliberately compact: about 150 words, roughly a minute of speech. It is the skeleton, not the full five minutes. At the pace in the time budget, the 'one request end to end' beat (1:30-3:00) would carry the extra detail, for example what the seller sees at each step and what happens if the upload fails halfway, and the two decisions (3:00-4:15) would each get a sentence on the alternative rejected and why. If cut to 90 seconds, the opening two sentences, one decision and the outcome are what survive.

Trade-offs and pitfalls

• Starting with the tech stack: the listener loses the purpose in the first thirty seconds.
• Telling every component with equal weight: it sounds like a diagram being read aloud.
• Inventing precise numbers: give scale and outcome honestly, in words you can defend.
• Ignoring the audience: check by eye or by asking whether to go deeper.

Direct answer

Write the record so a stranger can see the context, the options, the scoring, the decision and the conditions for reopening it. Use must-have gates first, then a weighted score for the remaining options, and test how easily the ranking flips. The weights guide the conversation; they do not make the decision. An ADR (architecture decision record) is a short dated document capturing one significant decision and why.

The record (illustrative; scores are the team's judgement)

ADR-021: Processing framework for the analytics platform
Status: Accepted    Date: 2026-09-01    Deciders: data platform team

Context
- Hourly and nightly batch transforms on order and clickstream data.
- A dashboard needing data within about 2 minutes. No use case needs sub-second results.
- The five-person team knows Spark and SQL well; nobody has run Flink in production.

Options
A. Apache Spark (batch, plus Structured Streaming, which processes small micro-batches)
B. Apache Flink (built for per-event streaming with event-time handling, meaning results follow when events actually happened rather than when they arrived, and managed state, meaning it stores running totals and lookups for you reliably)

Must-haves (pass/fail): runs in our cloud account; supports our data residency (data stays in the required countries); open-source licence.  Both pass.

Decision: Option A, Spark, for batch and near-real-time.
Consequences: no per-event latency guarantees; one skill set to hire for and support.
Revisit when: two or more use cases need end-to-end freshness under about 5 seconds with stateful joins, OR the team gains Flink experience, OR at the 12-month review.

A stateful join combines two live streams by remembering earlier events (for example matching a click to an order placed minutes before), which is where Flink's managed state matters most. Micro-batches are tiny batches run every second or so, which is how Spark fakes streaming.

Scoring the remaining options (1 to 5, higher is better)

Why those scores: workload fit is 3 for Spark and 5 for Flink because our need is minutes-fresh, not per-event, so Flink is a better fit but not essential. Skills are 5 versus 2 because the team knows Spark and has never run Flink. Operational effort is 4 versus 2 for the same reason plus Flink's state to look after.

Spark: 0.30x3 + 0.25x5 + 0.20x4 + 0.15x5 + 0.10x3 = 0.9 + 1.25 + 0.8 + 0.75 + 0.3 = 4.0.
Flink: 1.5 + 0.5 + 0.4 + 0.6 + 0.3 = 3.3.

Show how fragile the result is. Move weight to workload fit (50, 15, 15, 10, 10): Spark 1.5 + 0.75 + 0.6 + 0.5 + 0.3 = 3.65, Flink 2.5 + 0.3 + 0.3 + 0.4 + 0.3 = 3.8. The winner flips. Printing this in the record is honest: it tells the reader that Spark wins because the team values skills and low operational effort, and that a future need for low latency reverses it. Reversibility (how cheaply you could change the decision later) is a good tiebreaker when scores are close.

Should you force numbers? (a second decision, storage, same method)

Yes, as a discipline, with limits. The same team must also choose where to keep the data. Compare Parquet files (a compact columnar file format) on object storage (cheap file-like cloud storage), called a data lake, against a managed cloud data warehouse. Criteria and weights in order: cost 30, operational effort 25, performance 25, security risk 20. Lake scores in that order: cost 4, effort 3, performance 3, security 3. Warehouse: cost 3, effort 4, performance 4, security 3.

• Lake: 1.2 + 0.75 + 0.75 + 0.6 = 3.3. Warehouse: 0.9 + 1.0 + 1.0 + 0.6 = 3.5.
• Move 15 points of weight from operational effort to cost (45, 10, 25, 20): lake 1.8 + 0.3 + 0.75 + 0.6 = 3.45, warehouse 1.35 + 0.4 + 1.0 + 0.6 = 3.35. The ranking reverses.

Risks of false precision and guards

• A decimal looks like measurement. Round to one decimal and never report a gap under about 0.3 as a win (a rule of thumb): call it a tie and decide on reversibility.
• Scores should come from evidence (a proof of concept, meaning a small trial build, or a cost model), not opinion, and the source goes beside each score.
• Security and compliance belong in the must-have gates, not the weights, where a high score elsewhere could buy off a real risk.
• Record the weights before scoring, so nobody tunes them to a favoured answer.

Direct answer

A message-bus pipeline document is a contract with three audiences. Producers need to know what to send and what is promised on publish. Consumers need the delivery, ordering and duplicate rules, and what happens to a message that fails. Operators need retention, partition, capacity, alerts and replay steps. The diagram must show partitions, retries and the dead-letter path explicitly, because those are where delivery guarantees are decided.

Vocabulary first

• Broker: the server that receives messages and holds them until consumers read them.
• Topic: a named log of messages on the broker, like one labelled mailbox stream (here model-updates).
• Partition: one slice of a topic's log; messages with the same key always land in the same partition, which is why order is kept per key. The key is hashed to a number and mapped to a partition (for example hash 17 on 6 partitions is 17 mod 6 = partition 5).
• Consumer group: a set of consumers that share a topic, each partition going to exactly one member. With 6 partitions, at most 6 consumers in a group do useful work.
• Offset: a message's position number in its partition. Commit offset (acknowledge) means the consumer tells the broker "I have finished everything up to here", so a restart resumes after it.
• Retry with backoff: try again after a growing wait (for example 1 s, 4 s, 16 s) rather than hammering a failing system.
• Dead-letter topic: a separate topic where messages that keep failing are parked for a human, so they do not block the rest.
• Consumer lag: how many messages a consumer is behind the newest one in its partition.
• Retention: how long the broker keeps messages (here 7 days), which also limits how far back you can replay.
• Local outbox: a table in the producer's own database where the event is saved first, then sent to the broker later, so a broker outage cannot lose it.

What the document must tell each audience

Delivery semantics in plain terms

• At-least-once: a message is redelivered if the consumer does not acknowledge it, so duplicates are possible. It is the honest default: consumers acknowledge after processing succeeds.
• Exactly-once: across a network you cannot generally guarantee a message is delivered once. Some brokers offer transactional exactly-once inside the broker boundary, but side effects outside it (a database write, an email) still need protection. The practical claim to document is "at-least-once delivery plus an idempotent consumer", meaning processing the same message twice has the same effect as once, achieved by recording processed event ids.
• Ordering: guaranteed only within one partition (a subset of the topic's log). Choosing the key decides what stays ordered.

Diagram: partitioning, consumer groups, retry and dead-letter

flowchart LR
  P[Producer] -->|key = model_name| T
  subgraph T[Topic model-updates: 6 partitions, retention 7 days]
    P0[Partition 0]
    P1[Partition 1]
    P5[Partition 5]
  end
  P0 --> C1[Consumer A in group scorer]
  P1 --> C2[Consumer B in group scorer]
  P5 --> C2
  C1 -->|success: commit offset| OK[Acknowledged]
  C1 -->|failure: up to 3 retries with backoff| R[Retry topic]
  R --> C1
  R -->|still failing| D[Dead-letter topic, 14 days]
  D --> O[Alert and replay runbook]

Reading the diagram: partitions 2 to 4 are left out for readability. Trace one failing message: it arrives on partition 0, Consumer A fails to process it, so it is sent to the retry topic and comes back to Consumer A after a wait; after 3 failed retries it moves to the dead-letter topic, an alert fires, and an operator follows the replay runbook. On success the consumer commits the offset and the message is done.

Example: model-update publisher and its versioned event contract

A publisher announces each new machine-learning model version. Key by model_name so version 7 is never processed before version 6 for the same model. Consumers ignore any event whose version is not newer than the one they hold, which also makes duplicates harmless. Trace: a consumer holds version 13. Event version 14 arrives, it is newer, so the consumer applies it and now holds 14. The same event is redelivered because the acknowledgement was lost (a duplicate): 14 is not newer than 14, so it is ignored. A late version 13 arriving afterwards is also ignored.

{
  "event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "event_type": "model.updated",
  "schema_version": "1.2",
  "occurred_at": "2026-09-28T09:15:00Z",
  "model_name": "fraud-scorer",
  "model_version": 14,
  "artifact_uri": "registry://models/fraud-scorer/14"
}

Schema evolution rules

• Adding an optional field is safe: old consumers ignore it.
• Removing, renaming or changing the type of a field is breaking: publish to a new versioned topic (for example model-updates.v2) and run both for a deprecation window.
• Never reuse a field name with a new meaning.
• Every event carries schema_version; consumers must tolerate unknown fields.

Failure behaviour, stated unambiguously

Pitfalls: saying "exactly-once" without saying where; a diagram with a single arrow labelled "queue"; forgetting that the dead-letter topic needs an owner and an alert, or it becomes a silent graveyard.

Direct answer

No single diagram describes a distributed service, so I draw a small set where each answers one question: context (who and what surrounds the system), container (what deployable pieces it is made of), sequence (what happens over time in a key flow, including failure), deployment (where it runs), and, when needed, component (the inside of one complex container), data flow and state diagrams: seven in all, matching the table below. These follow the C4 model (Context, Container, Component, Code: four zoom levels) plus UML (Unified Modeling Language, a standard diagram notation) style sequence diagrams (participants across the top, time flowing down) and state diagrams (the states an entity moves through and what triggers each move). Start with context, container and sequence: those three are asked about most; data flow and state are occasional. For SREs (site reliability engineers, who run the service in production) I lead with deployment, component and failure sequence; for a mixed audience I show context, container and one happy-path sequence (the flow where nothing goes wrong).

Which diagram answers which question

SRE review versus mixed audience

• SREs: a component view (the internal structure of one service) plus a deployment view, then a sequence of the failure path and the dependency list with timeouts. They want blast radius (how much breaks when one part fails), capacity and failover.
• Mixed audience (product, QA, engineering): context, container in plain names, and one narrated sequence. No cloud-icon wall, no acronyms without a legend.

Worked example: mobile client, API, auth service, database

1. Context: User, Mobile app system, external identity provider.
2. Container: Mobile app, API, Auth service, Database, each with a one-line responsibility.
3. Sequence: app sends login, API asks Auth, Auth checks the database, token returns. Timeout on the Auth call is stated (for example 2 seconds).
   That is three views for three questions, not one overloaded picture. The sequence for the login flow, drawn as Mermaid:

sequenceDiagram
  participant M as Mobile app
  participant A as API
  participant U as Auth service
  participant D as Database
  M->>A: login(user, password)
  A->>U: verify credentials (timeout 2 s)
  U->>D: look up user
  D-->>U: user record
  U-->>A: token
  A-->>M: token

And the container view as text, one line per box:

Mobile app -> API      : HTTPS, JSON
API        -> Auth     : verifies credentials
Auth       -> Database : reads user records

Conventions I apply to all of them

• Naming: use the same names as the code repository and dashboards, one name per thing.
• Tools: diagrams as code (Mermaid, PlantUML and Structurizr are text-based diagram tools; Mermaid is the easiest start because many Git hosts render it directly) kept in the repository so changes are reviewed in pull requests; a drawing tool for one-off workshop sketches.
• Annotate: state assumptions ("peak 500 requests per second, assumed"), non-functional requirements (NFRs, targets such as availability or latency), and a version and date on each diagram.
• QA audience: sequence and state diagrams are what testers turn into test cases, and the context view shows integration points to stub (replace with a fake in tests).

Trade-offs and pitfalls

• Drawing all diagrams for every service is wasted effort; draw the ones whose question is open.
• Mixing levels (a database next to a class name) is the most common defect and confuses every reader.