Architecture Documentation and Communication Questions
Making an architecture legible to others: architecture decision records (templates, alternatives and consequences, lifecycle, supersession, tagging and discoverability), diagramming and visualization (C4, sequence, deployment, data-flow and trust-boundary diagrams, notation conventions), and communicating designs to technical and non-technical stakeholders. Covers capturing rationale, documenting what a system does under failure, load and consistency trade-offs, recording observability, SLO and security content, running design reviews, keeping docs and diagrams current, and presenting a system clearly under time pressure. The communication skill that separates a good design from an understood one.
You depend on external systems for tax calculation, identity verification and analytics. How do you document each integration point so the failure behaviour and ownership are clear to someone on call?
Sample Answer
Direct answer
For each external dependency I keep one short "integration card" in the repo of the service that calls it, written for the person on call: what the dependency does for us, who owns it on both sides, how it fails, what our system then does, what the user sees, and where to look first. The failure behaviour must be decided and written down per dependency, because "the tax API is down" needs a different response from "the analytics API is down".
The card (fields)
- Purpose and criticality: what breaks for users if it is gone (blocks checkout, degrades, invisible).
- Owner: our owning team and on-call channel, plus the vendor's support route, account or contract reference, and status page.
- Call details: endpoint, timeout, retry policy, circuit breaker (a switch that stops calling a failing dependency for a while so it can recover and so we do not pile on).
- Failure behaviour: fail closed (refuse the action) or fail open (proceed without it), any fallback, and what the user sees.
- Data sent: especially personal data, which affects vendor risk and incident duty.
- Signals: dashboard link, the alert, and what "unhealthy" means.
- Runbook link (a step-by-step operating guide) with first three steps, and the credential rotation procedure.
Worked example: the three dependencies (timeouts and thresholds are illustrative values to be tuned)
| Tax calculation | Identity verification | Analytics | |
|---|---|---|---|
| Criticality | High: needed to price an order | High for new high-risk accounts, none for existing users | Low: no user impact |
| Timeout / retry | 2 s, one retry | 5 s, no automatic retry (the vendor step is not safe to repeat blindly) | 500 ms, none |
| On failure | Fail closed for checkout by default; finance may approve a fallback to last known rates per region, with orders flagged for reconciliation | Fail closed: put the account in "pending review" and queue for later retry or manual review | Fail open: drop or buffer events, never block the request |
| User sees | "We cannot calculate tax right now, try again shortly" | "Verification is taking longer than usual, we will email you" | Nothing |
| Page the on-call? | Yes when error rate stays high for 5 minutes | Yes when the pending queue keeps growing | No, ticket only |
| Vendor-side owner | Vendor support plus account manager | Vendor support | Vendor support |
Notice that the fallback for tax is a business and legal decision, so the card names who approved it, rather than an engineer guessing at 3 a.m.
How the card helps at 3 a.m.
The on-call engineer reads the page from the alert, sees "fail closed, checkout blocked, check vendor status page, then the circuit breaker dashboard", and knows within a minute whether the problem is theirs, the vendor's, or a bad credential.
Trade-offs and pitfalls
- Documenting only the happy-path API contract is the common miss; the failure column is the valuable one.
- Cards rot. Put them next to the code, require a card in the pull request that adds a new integration, and review them when the vendor contract renews or an incident involves that vendor.
- Do not copy the vendor's docs into the card; link to them and record only our decisions and our numbers.
What security and authentication content must an architecture document for a public API contain, and how do you present it to a security reviewer versus a developer?
Sample Answer
Direct answer
The document must state, for a public API, who can call it, how callers prove who they are, what they are allowed to do, how data is protected in transit and at rest, and how abuse is limited and detected. A security reviewer wants threats, controls and evidence; a developer wants how to authenticate correctly and what errors to expect. I would write one source of truth and give each reader a different entry point into it.
Required content
- Authentication: the mechanism (for example OAuth 2.0, the standard for delegated access, with short-lived access tokens (an access token is a temporary string the caller sends with each request to prove it was authorised), or API keys for server-to-server use), where tokens are issued, lifetime, refresh and revocation.
- Authorization: the model (scopes are named permissions carried on the token, such as
orders:read; roles group permissions by job) and where it is enforced (gateway versus service), including object-level checks (a caller must own the record it requests: if user A asks for/orders/1002and that order belongs to user B, the API must refuse, even though A's token is valid; broken object-level authorization is the top risk in the OWASP API Security list, OWASP being an open security-community project). - Trust boundaries and data flow: what is exposed publicly, what sits behind the gateway, and where TLS ends (TLS is the encryption that protects traffic on the network; "where it ends" is the point where traffic is decrypted and must be trusted from then on).
- Data protection: encryption in transit and at rest, classification of fields, what is never logged.
- Abuse controls: rate limits, quotas, input validation, size limits, and how bad clients are blocked.
- Threat model: a threat model is a structured list of what could go wrong and who might attack, each threat paired with the control that answers it. Record the residual risk (what remains after the controls) and the named person who accepts it.
- Secrets and key management, audit logging, incident contacts.
Presenting to each reader
| Security reviewer | Developer | |
|---|---|---|
| Opens with | Threat table and trust-boundary diagram | "How to get a token" with a copyable request |
| Format | Threat, control, evidence (config link, test, scan result), residual risk | Step-by-step, examples, error codes, scope table |
| Cares about | Gaps, assumptions, compliance mapping (which control satisfies which regulation or standard requirement) | Time to a working, correct call |
Worked example (illustrative fragment)
Security reviewer fragment, threat table rows:
| Threat | Control | Evidence | Residual risk |
|---|---|---|---|
| Stolen access token replayed | 15-minute lifetime; sender-bound refresh tokens (a refresh token that only the client it was issued to can use, so a copy is useless); revocation list at the gateway (token ids refused even before they expire) | Gateway policy file, revocation test | Up to 15 minutes of misuse, accepted by the security owner |
| User A reads user B's order by changing the id in the URL | Service checks the order's owner equals the caller on every read | Automated test that requests another user's order and expects a refusal | None known; retested each release |
Developer fragment, the "how to get a token" page (client-credentials grant means a server application exchanges its own id and secret for a token, with no human user involved; a bearer token is one that works for whoever holds it, so it must be sent only over TLS):
POST /oauth/token
grant_type=client_credentials&client_id=<your-id>&client_secret=<your-secret>&scope=orders:read
-> {"access_token": "<token>", "expires_in": 900}
GET /orders/1002
Authorization: Bearer <token>
Errors: 401 means the API does not know who you are (no token, malformed or expired), so fetch a new token. 403 means it knows who you are but you may not do this (the token lacks the scope, or the order is not yours), so requesting a new token will not help. That difference is authentication (proving who you are) versus authorization (what you are allowed to do).
Pitfalls: describing the design without evidence a reviewer can check; documenting the mechanism but not the failure responses; putting secrets or real tokens in examples; letting the doc and the gateway configuration diverge. Generate the developer reference from the API's OpenAPI description (a machine-readable file listing every endpoint, parameter and response) where you can, so it cannot drift.
Two teams use different icons and naming in their architecture diagrams, and it is confusing readers. How do you get to a shared convention, what do you require in the docs, and how do you make it stick?
Sample Answer
Direct answer
I would not pick a winner between the two teams' styles. I would run one short working session with both teams and a few readers, agree on a minimal shared convention built on an existing notation (for example the C4 model, a common way to draw architecture at four zoom levels: context, container, component and code views), record it, and enforce it with a template and an automated check so it survives after the meeting. The aim is fewer than ten rules that fix the actual confusion, not a style guide nobody reads.
Step 1: diagnose what actually confuses readers (a day)
Collect five or six real examples: the same service called "Payments Svc" in one diagram and payments-api in another, a cylinder meaning "database" in one and "queue" in the other, one team colouring by owner and the other by environment. Ask readers, such as on-call engineers and new hires, which ambiguity cost them time. That evidence keeps the debate off taste.
Step 2: agree the convention (one 60-minute session)
Both teams attend, I facilitate, and the decision rule is stated up front: the readers' confusion decides, not team preference. Output, for example:
- Names come from the service catalog (the registry listing every service with its exact name and owner), exactly as registered.
- One shape means one thing: box for service, cylinder for datastore, a queue symbol for message queue; vendor icons only inside a labelled cloud boundary.
- Solid arrow for synchronous call, dashed for asynchronous; arrows point in the direction of the call.
- Colour is reserved for one meaning (health, or environment), never for teams.
Step 3: what the docs must contain
Every diagram needs: a title that states its type and level (for example "Container view: checkout"), a legend, an owner, the date last reviewed, and a link to the diagram source file, not only an image. The decision is recorded as a short ADR (architecture decision record: a dated note stating the decision and why), so nobody reopens it without new evidence.
Step 4: make it stick
- Ship a template and a shared icon and shape library in the diagramming tool, so following the convention is the easy path.
- Add a check in continuous integration (the automated build that runs on each change) for diagrams stored as text: names must exist in the catalog, a legend and owner must be present.
- Add one line to the review checklist for architecture pull requests.
- Migrate old diagrams when they are next edited, not in a big-bang rewrite (redrawing everything at once, which stalls and gets abandoned); name a champion in each team (one person who answers questions and nudges colleagues).
- Review after one quarter: which rule was ignored, and why?
What "diagram as text" and the check look like (illustrative)
A text diagram is a small file that a tool renders into a picture, so it can be reviewed like code. For example, a Mermaid file docs/checkout.mmd:
flowchart LR
web["web-store"] -->|sync| pay["payments-api"]
pay -.->|async| q[("payment-events queue")]
A CI check reads the names in the file and compares them with the catalog. If payments-api were mistyped as "Payments Svc", the build would fail with a message like this (wording depends on the script you write):
docs/checkout.mmd: unknown service name "Payments Svc" (not in catalog). Did you mean "payments-api"?
docs/checkout.mmd: missing legend
Trade-offs and pitfalls
- A strict, long standard gets ignored; a five-to-eight-rule standard survives. I would drop any rule nobody can point to a confusion for.
- If one team's diagrams are generated from code, adopt its naming as the base, because a rule that is enforced by a tool beats one that relies on discipline.
- If the two teams have a history of conflict, get their shared manager to endorse the outcome, but do not let it become an order handed down; adoption came from the teams shaping it.
Which architecture diagram would you show to executives, to engineering leadership and to the engineers implementing a change? How do a high-level and a detailed diagram differ in what they must include and avoid?
Sample Answer
Direct answer
Three audiences, three diagrams from the same underlying model. Executives get a system-context picture with a few boxes in business language. Engineering leadership gets a container-level view showing major services, datastores, ownership and risk. The implementing engineers get a detailed diagram of the specific change: components, interfaces, data flow and failure paths. The high-level diagram must show purpose, boundaries and risks and avoid technology detail; the detailed one must show interfaces and behaviour and avoid the whole-system sprawl.
Which diagram for whom
| Audience | Diagram | Must include | Must avoid |
|---|---|---|---|
| Executives | System context (C4 level 1: the system, its users, its neighbours) | Users, the product as one box, external systems, one risk marker, plain labels | Protocols, cloud service names, internal services |
| Engineering leadership | Container diagram (C4 level 2: services, datastores, queues) | Owners, dependencies, regions, where the change lands | Class or library detail, every endpoint |
| Implementing engineers | Component diagram of the affected service (C4 level 3: the parts inside one service) plus a sequence diagram of the changed flow (not a C4 level: it lists the parts across the top and shows the messages between them in time order, top to bottom, for one scenario) | Interfaces, data formats, error paths, what is changing (highlighted) | Unchanged parts drawn in full, marketing wording |
Visual conventions and audience assumptions
- Executives: one colour for "this is what changes", nothing else coloured, and no cloud vocabulary without a gloss. State the assumption on the slide, for example "assumes no cloud background".
- Leadership: colour by owning team, so ownership gaps are visible.
- Engineers: bold or dashed outlines for the changed parts, so review focuses on the diff.
Worked example: ML recommendation service
A recommendation service is a machine learning model that suggests products to a shopper. One diagram, three layers, drawn on the same canvas or as a toggle so the shared names and arrows agree.
- Backend engineers see the request path: API, feature lookup (fetching the stored facts about this shopper, such as recent clicks), model server (the program that runs the trained model and returns suggestions), cache.
- Data scientists see the training loop: raw events, feature store (a database of prepared inputs for the model), training job (the run that fits the model to past data), model registry (the versioned catalogue of trained models).
- Product managers see a simplified strip: shopper, "suggestions", business KPI (key performance indicator: click-through, the share of shown suggestions that get clicked).
Shared across all three layers: the boxes "Shopper", "Recommendations" (the model server plus its model) and "Suggestions". These keep one name each. The implementing engineer's diagram for, say, a change to feature lookup shows the API, feature lookup and feature store as full boxes, with the changed feature lookup drawn in a bold outline and a note "new: reads shopper's last 10 clicks"; the training loop appears as one greyed-out box so it does not compete for attention.
Pitfalls
- Showing engineers the executive picture (no actionable detail) or executives the engineer picture (noise).
- Different names for the same thing across the diagrams.
- No legend, no date, no owner: a diagram nobody can trust is worse than none.
Two candidate designs were seriously considered for a service-to-service call path, and the losing option had real merits. How do you make the rejected alternative visible in the record so that a future engineer does not reopen the debate blindly? Should it live in the same record or a separate one?
Sample Answer
Direct answer
Make the rejected option a first-class part of the same decision record (an ADR, architecture decision record: a short dated note capturing one significant design decision and why), with an honest "Alternatives considered" section: what the option is, the real merits it had, why it lost under the constraints of the moment, and the specific condition that would reopen the question. Keep it in the same record by default because the reader looking at the chosen design is exactly the one who will ask "why not the other one?". Use a separate record only in the narrow cases below.
How to write the rejected alternative so it prevents a blind reopening
- Steelman it (present the opposing option in its strongest, fairest form): state its strengths in terms its advocates would accept. A strawman (a weak, distorted version that is easy to knock down) invites someone to "rediscover" the option.
- Name the criteria and how each option scored (a small table, qualitative labels are fine).
- State why it lost: the constraint or weight that decided it, and dated to the context ("with a two-person team and no broker experience").
- Give a revisit trigger: the measurable change that would reopen the debate.
Worked example: service-to-service call path (Orders needs a price from Pricing)
(gRPC is a common way for one service to call another directly and wait for the answer. A message broker is a middle service that holds messages so a sender can publish an event without waiting, and receivers pick it up later. Asynchronous means the sender does not wait for the reply.)
| Criterion | A: direct gRPC call (chosen) | B: asynchronous events via a message broker |
|---|---|---|
| Customer sees price immediately | Yes | Needs a cached or stale price |
| Coupling and outage tolerance | Weaker: Pricing outage hurts checkout | Strong: Orders keeps working |
| Operational burden | Low | New broker to run and monitor |
| Team experience | Strong | None today |
Alternatives section text: "Option B (events) has real merits: it isolates checkout from Pricing outages and scales to many consumers. We rejected it because checkout must show the exact price synchronously, and the team has no operating experience with a broker. Revisit if Pricing availability becomes the leading cause of checkout failures, or three or more services need price changes." If someone reopens it later, they start from those conditions instead of from zero.
Same record or separate?
- Default: one ADR per decision, alternatives inside it. Discoverability is best because the reader finds the alternatives exactly where they look for the decision.
- Separate ADRs when the decisions are genuinely independent (choosing the wire protocol, the format and rules for messages sent between services, versus choosing service discovery, the way services find each other's network addresses); bundling them hides one decision behind another.
- A standalone "Rejected" record when an alternative is a big proposal with an independent life, such as one that went through its own RFC (request for comments, a circulated proposal) and may come back. Link it from the chosen ADR and give it status Rejected.
- Never spread one decision's alternatives across several files with no links: nobody will piece them together.
Evaluation criteria list (regional-cache ADR)
For an ADR choosing a regional cache (a copy of frequently read data kept close to users in each region): read-latency improvement, tolerance for stale data, invalidation approach (how cached copies are cleared or refreshed when the source changes), operational complexity, cost, behaviour when the cache is down, and data-residency limits by region (rules that certain data must stay in certain countries). Listing criteria before options keeps the comparison fair.
Illustrative scoring (1 to 5, higher is better; the team's judgement) for two options, a per-region cache and a single central cache:
| Criterion | Per-region cache | Central cache | Why |
|---|---|---|---|
| Read latency | 5 | 2 | Regional reads stay local; central reads cross oceans |
| Stale-data tolerance | 3 | 4 | Many copies take longer to refresh |
| Data residency | 5 | 1 | Central copy may hold data that must stay in-region |
| Operational complexity | 2 | 4 | Many caches to run |
Data residency is really a pass/fail gate: if some data may not leave a region, the central option is out for that data whatever it scores elsewhere. The scores then show the trade: better latency and compliance against more to operate.
Trade-offs and pitfalls
- Alternatives written after the fact to justify the choice: readers detect this.
- Editing the ADR when you change your mind: write a new one that supersedes it and links back.
- No revisit trigger: the debate returns at the next architecture meeting.
Unlock Full Question Bank
Get access to all Architecture Documentation and Communication interview questions and detailed answers.
Sign in to ContinueJoin thousands of developers preparing for their dream job.