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 are writing the architecture guide for a project. Which principles would you include, how would you illustrate each with an example, and how would you tell whether teams follow them?
Sample Answer
Direct answer
I would include five to seven principles, each written in the same short form: statement, reason, example, and how we check it. If a principle cannot be checked in some way, it is a slogan and I would cut it. Adherence is measured mostly by automated checks in the build (architecture "fitness functions": tests that fail when a rule is broken), plus a light review trail through architecture decision records (ADRs: short dated notes on why something was decided), and by tagging incidents that traced back to a broken principle.
One guide entry, filled in (Principle 2)
- Statement: every remote call has a timeout and a defined fallback.
- Reason: a slow dependency without a timeout ties up threads and stalls the caller (the worked example below shows it).
- Example: the payment call times out after 2 seconds and shows "try again" instead of hanging the page.
- How we check it: a lint (an automated scan of the code for a rule violation) fails the build if a client is created without a timeout.
Example principles (each with example and check). If you can only adopt two at first, start with 1 (one owner per dataset) and 2 (timeouts), which cause the most painful incidents.
| Principle | Example | How we tell |
|---|---|---|
| 1. Each dataset has one owning service that writes it | Orders are written only by the order service; others read via its API or events | A test or dependency rule fails if another service imports the order data access code or holds credentials to that database |
| 2. Every remote call has a timeout and a defined fallback | Payment call times out after a set limit and shows "try again", never hangs the page | Lint or contract test scans clients for missing timeouts; game-day drill (a rehearsed failure, such as switching a dependency off on purpose to see what happens) |
| 3. Change APIs compatibly (add, do not break) | New optional field, old clients keep working | Contract tests (tests that replay old clients' requests against the new version) run in CI (continuous integration, the automated build and test run) |
| 4. Observable by default | Every service emits request logs, metrics and traces with a shared correlation id (one identifier passed along every call so a request can be followed across services) | Service template check; service cannot go to production without a dashboard link |
| 5. Prefer reversible decisions | Feature flags (switches that turn a change on or off without redeploying) for risky changes, expand-then-contract database migrations (add the new column first, move readers over, remove the old column last, so each step can be undone) | Review question on each ADR: "how do we undo this?" |
| 6. Secure by default | No secrets in code, least privilege (each account gets only the access it needs) for service accounts | Secret scanning (a tool that searches commits for passwords and keys) in CI, periodic access review |
How to measure following it
- Leading (a signal you can act on before harm occurs): percentage of services passing each automated check, number of open exceptions and their age. For example, if 18 of 24 services pass the timeout lint, adherence is 18 / 24 = 75%, and the 6 failing services are the work list.
- Lagging (a signal that shows up after harm): incidents whose review names a principle. If timeouts keep appearing in postmortems (written incident reviews), the principle exists but is not landing.
- Exception process: a team can break a principle by writing an ADR with an expiry date. Exceptions are visible and finite.
Worked example (illustrative)
Principle 2 (timeouts) fails in a review: the search service calls a pricing service with no timeout, and a slow pricing service stalls search. The guide's entry gives the fix pattern (timeout, retry with limit, fallback price), the check (client lint), and the owner of the exception if a team cannot comply this quarter.
Trade-offs and pitfalls
- A long list nobody remembers. Pick the few that have hurt this project.
- A guide enforced only by an architecture review board becomes a bottleneck; encode checks so teams get feedback in minutes.
- Principles must state their limits: "prefer managed services unless cost or control says otherwise", not an absolute.
Your architects want accepted decisions to be checked automatically when engineers change code. What would you check in CI, what would you keep as human review, and what can go wrong if the checks are too strict?
Sample Answer
Direct answer
Automate only what is objective and cheap to decide, warn before you block, and leave judgement to people. Concretely: check structural rules (a forbidden dependency, a missing encryption setting, a malformed ADR) in CI (continuous integration: the automated checks that run on every pull request). Keep human review for whether a decision still fits, whether an exception is justified, and trade-offs the code cannot express. Too-strict checks fail by producing false alarms, blocking urgent fixes, and teaching engineers to route around them.
What to check in CI (architecture "fitness functions": automated tests that an architectural property still holds)
| Check | Example | Why a machine can decide it |
|---|---|---|
| Forbidden dependency | A PR bot (an automated account that comments on pull requests) for an ADR saying "no synchronous calls between services in the checkout path": flag a new client import of another service in that code | It is a pattern in code or manifests (files that list what a service deploys and depends on) |
| Required configuration | Infrastructure code creates a datastore without encryption enabled | It is a property in a file |
| ADR structure lint | Title, status, date present; status from an allowed list; links resolve; required sections present | It is format, not meaning |
| Exception hygiene | Every exception cites an ADR, an owner and an expiry date | A record either has the fields or not |
| Feature-flag gating | Code that deviates from an accepted ADR during migration is only allowed behind a registered flag (a named on/off switch listed in a central registry) with an expiry | Flag registry lookup |
What stays human
Is the decision still right given new facts? Is this exception justified? Is a new pattern a better option than the ADR's? Does a change quietly create a decision that needs its own ADR? Reviewers use a short checklist, and architects join only for tier-1 (the most business-critical services, such as payments) or cross-team changes.
ADR lint rules that do not block good contributions
- Required: title, status (from a fixed list), date, and the Context, Decision and Consequences sections. Optional: alternatives, links.
- Naming:
ADR-0012-short-title.md, with the ID matching the file name. - Link validity: relative links must resolve; a superseded ADR must link its replacement.
- Leniency: ADRs in
proposedstatus get warnings only, so a draft can open a discussion. Strict rules apply once accepted. A docs-only PR is never blocked by code rules. Failure messages say exactly what to fix.
Exceptions across teams
A central register, for example exceptions.yaml, keyed by ADR ID, with a reason, owner team and expiry date. Expired entries fail the check, so exceptions cannot become permanent by neglect.
rules:
- id: no-sync-cross-service-calls
adr: ADR-0012
mode: warn # warn first, switch to block after tuning
applies_to: services/checkout/**
exceptions:
- rule: no-sync-cross-service-calls
where: services/checkout/inventory_lookup.py
reason: Stock check must be synchronous until ADR-0031 lands
owner: checkout-team
expires: 2026-12-31
Reading the file: mode: warn means a match only posts a comment and does not block the merge. applies_to limits the rule to files under services/checkout/. Walk-through for a PR that edits services/checkout/inventory_lookup.py and adds a synchronous call to another service: the file is in scope, but it matches an exception naming the rule, this file, an owner and an expiry, so the bot stays quiet (or notes "allowed until 2026-12-31, owner checkout-team"). The same change opened on 2027-01-05 finds the exception expired, so the call is reported again: as a warning while the rule is in warn mode, as a failed check once the mode is block. The same call in services/search/ is out of scope and this rule ignores it.
Worked example (hypothetical numbers): the bot runs in warn mode for four weeks and comments on 20 PRs. If 12 of the 20 needed an exception, 12 divided by 20 is 60%, which says the rule is wrong or the ADR is out of date, not that engineers are careless. Tune the rule or supersede the ADR before you switch to block.
Separately, check the false-alarm rate on the same trial: if 3 of the 20 warnings were wrong calls (the code did not really break the ADR), that is 3 divided by 20, or 15%, which is over a 10% budget, so the rule stays in warn mode until its detection is fixed.
What goes wrong when checks are too strict
- False positives train people to ignore or bypass the check.
- A hotfix at night is blocked by a style rule. Provide an audited override label (a tag a human adds to the pull request to bypass the check, recorded with who added it and why).
- Gaming: blanket exception entries, or wrapping calls so the pattern is not detected.
- Rules outlive their ADR. Each rule names its ADR, and if that ADR is superseded the rule is flagged for review.
- Slow or flaky checks make CI a tax.
- Unowned rules rot. Assign an owner and review override rates every quarter.
Guards: warn-first mode, expiring exceptions, a false-positive budget (an agreed ceiling on how many warnings may be wrong before the rule must be fixed, for example 1 in 10), and every failure message linking the ADR that explains why.
You are authorising a major architectural change. Which measurable success criteria do you write into its decision record, how do you tie each to instrumentation, and how do you make sure someone actually checks them after sign-off?
Sample Answer
Direct answer
Write success criteria as numbers with a baseline, a target, a measurement method and a review date, not as adjectives. Each criterion must point to a specific metric that existing or new instrumentation emits. After sign-off, make checking automatic: a scheduled review with a named owner, a dashboard, and an ADR (architecture decision record: a short document capturing one decision) status that changes only when the review happens.
Criteria table in the record
Worked example: a major architectural change, a shared cache added in front of a read-heavy product API (metrics for a caching layer: latency, hit rate, staleness). The numbers are illustrative.
| Criterion | Baseline | Target | Instrumentation | Owner |
|---|---|---|---|---|
| p95 latency (95% of requests are faster than this) of product reads | 420 ms, measured last month | at most 150 ms | latency histogram from the service | Service lead |
| Cache hit rate = hits / (hits + misses) | n/a | at least 80% after two weeks | cache hit and miss counters | SRE |
| Database read QPS (queries per second) | 2,400 at peak | at most 600 (an 80% hit rate would give 2,400 x 0.2 = 480) | DB metrics | SRE |
| Staleness: age of data served | n/a | never above the agreed TTL (time-to-live) | timestamp on cached entries, sampled | Service lead |
| Guardrail: checkout conversion (KPI, key performance indicator) | 3.1% | not below 3.0% | product analytics | Product |
For arithmetic: with 8,000 hits and 2,000 misses, hit rate = 8,000 / 10,000 = 80%, and the database sees 2,000 of the original 10,000 reads, a fall of 80%.
Tying each criterion to instrumentation
- A criterion with no metric is a wish. If instrumentation does not exist, building it is part of the decision's cost and goes in the record.
- Record the baseline before the change ships; otherwise "improved" cannot be proven.
- Use both technical and business measures. For a move to event-driven architecture (services communicate through published events rather than direct calls), technical metrics are consumer lag (how many messages are waiting unprocessed because the consumer is behind) and end-to-end event latency; business KPIs are order-to-fulfilment time and failed-order rate. Show them on one dashboard so engineering and product read the same page.
- Include a guardrail metric that must not get worse (error rate, checkout conversion) so a "win" on one number cannot hide damage elsewhere. Traced example: after launch, hit rate is 85%, p95 is 120 ms and DB reads are 360, so every speed target is met. But conversion fell from 3.1% to 2.6%, because stale prices on product pages confused shoppers. The guardrail exposes the hidden loss and forces a Revisit.
Making sure someone actually checks
- Owner and date in the record. "Review at 30 and 90 days, owner: checkout lead."
- Calendar entry and ticket created at sign-off, not "we will remember".
- Audit checkpoints and roles. Checkpoints are the scheduled points where someone checks the numbers. The owner presents the numbers; an architecture forum (a standing group of senior engineers that reviews significant decisions) or engineering manager confirms; SRE confirms the instrumentation still works.
- Status discipline. The ADR moves from Accepted (approved, not yet proven) to Validated (review confirmed the targets were met) or Revisit (targets missed, the decision is reopened) when the review finishes, and a dashboard shows ADRs whose review date has passed with no outcome.
- Decide the consequence up front. If a target is missed, say what happens: tune, roll back, or accept and record why.
Trade-offs and pitfalls
- Gaming: a hit-rate target alone can be met by caching trivial data. Pair it with latency and DB load.
- Too many criteria dilute attention; three to five, with one primary.
- Targets picked after seeing results, which proves nothing. Write them before implementation.
- Measurement that breaks silently after a refactor: include a test or alert that the metric is still being emitted.
How do you document a software architecture so others can understand it? Walk me through your approach, from who the readers are to what you produce.
Sample Answer
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?
| Reader | Their question |
|---|---|
| New engineer | How is it organised and where do I start? |
| On-call SRE (site reliability engineer) | What breaks, what depends on what, where is the runbook (the step-by-step guide for handling an alert)? |
| Security reviewer | Where is data stored and where are the trust boundaries (the lines where data passes between zones trusted differently, such as the internet and your servers)? |
| Business or client stakeholder | What does it do for us, what does it cost, what are the risks? |
Step 2: What I produce
- 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.
- 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.
- 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.
- Data view: what is stored where, who owns it, what is sensitive.
- Deployment view: what runs where.
- Decision records (ADRs, architecture decision records: one-page notes on a single decision) for the important choices: the "why".
- 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.
You are submitting a proposal for a distributed caching layer to your architecture review board. What must the submission contain for the board to make a decision, what would make them send it back unread, and how do you keep it reviewable?
Sample Answer
Direct answer
The submission must let the board decide from the first page: what is being asked, why, the options considered, the recommendation, the risks and how to back out. Boards send proposals back unread when there is no clear ask or evidence. Keep it reviewable with a short core, an appendix for detail, and time for questions before the meeting. An ARB (architecture review board) is the group that approves significant design changes. A distributed cache is a shared in-memory store that many application instances read before the database.
What the submission must contain
| Section | What to put in it |
|---|---|
| Decision requested | One sentence, an approver, and a date (example below) |
| Problem and evidence | Measured read load, database latency, cost of doing nothing |
| Options | No cache; in-process cache (held in each application instance's own memory); managed Redis-compatible cache (a hosted service speaking the Redis protocol); each with pros and cons |
| Design | One component diagram and the cache-aside flow (below) |
| Capacity assumptions | Key count, value size, overhead, replication, and how they were validated |
| Failure modes | Cache down, cold start, stampede, stale data |
| Rollout and rollback | Flag, ramp, rollback trigger |
| Security | Authentication, encryption in transit, what data may be cached |
| Monitoring | Hit rate, latency, evictions, memory, replication lag, with alerts |
| Cost, risks, open questions | Named owners |
flowchart LR
app[Application] -->|"1 read"| cache[(Cache)]
cache -->|"2 miss"| app
app -->|"3 read on miss"| db[(Database)]
app -->|"4 fill cache"| cache
Example first page (illustrative)
Decision requested: Approve a managed distributed cache for the product-catalogue reads. Approver: Architecture Review Board chair. Needed by: the 14th, so the rollout can start next sprint. Why: database read latency is the top cause of slow page loads; measured peak is 4,000 reads per second. Recommendation: managed cache using the cache-aside pattern (the app checks the cache first and fills it on a miss), rolled out behind a flag with one-step rollback.
Worked example for caching (illustrative inputs)
- Memory: 20 million keys x 2 KiB = 40,960,000,000 bytes, about 38.1 GiB (a KiB is 1,024 bytes and a GiB is 1,024 x 1,024 x 1,024 bytes). Add an assumed 30% overhead for metadata (the store keeps per-key bookkeeping such as the key name, expiry and internal pointers, beyond the value itself): 38.1 x 1.3 = about 49.6 GiB. Keep two copies for failover (a replica holds a full copy so a failed node can be replaced without an empty cache): 49.6 x 2 = about 99.2 GiB across the cluster. The 30% is an assumption to confirm with a load test.
- Why failure modes matter: at 4,000 reads per second with a 90% hit rate (the share of reads answered from the cache), the database serves 4,000 x 0.10 = 400 reads per second. If the cache is lost, all 4,000 reach the database, 10 times the usual load. This is a cache stampede (many requests hitting the database at once). Board question: is the database sized for that, or does the design shed load?
- Mitigations to state, in priority order for a first proposal:
- Core: a load test at cold-cache traffic (start with an empty cache, the cold start, and confirm the database survives). This is the evidence the board wants.
- Core: request coalescing (many requests for the same missing key share one database read).
- Core: randomised expiry (TTL, time-to-live, plus a small random jitter so keys do not all expire together).
- Optional detail: a circuit breaker (a guard that stops calling a failing dependency and sheds load) can be mentioned in the appendix; it is a refinement, not a first-page item.
- Staleness: TTL plus explicit invalidation on write, with a stated maximum stale time.
- Rollout: shadow reads first (the app also reads the cache and compares with the database, but still serves the database result), then a feature flag (a switch that turns the new path on or off without a deploy) ramped in steps such as 1%, 10%, 50%, 100%; rollback is turning the flag off, with the database kept sized for the fallback.
- Evictions are entries the cache discards when memory is full, and replication lag is how far a replica is behind the primary; both belong on the monitoring dashboard.
What sends it back unread
- No stated decision or approver.
- No measured problem, only "it will be faster".
- One option only, presented as decided.
- No failure, rollback or security section.
- A long unstructured document or an unfilled template.
- Submitted the day before the meeting.
Keeping it reviewable
- A two-page core with the appendix behind it, and a summary of what changed since the last version.
- Pre-read circulated several days ahead, and a pre-review with one board member.
- Questions you expect are answered in the document, not saved for the 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.