Architecture Documentation and Communication Questions

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)

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.

Direct answer

Give non-functional requirements (NFRs: qualities such as speed, availability and compliance, as opposed to features) their own section with a stable ID, a measurable target, the conditions of measurement, an owner and a named way to verify each one. Then keep them visible by referencing the IDs in decision records, pull request templates, test names and dashboards. A reader can test a requirement only if a stranger could write a pass/fail check from the wording alone.

The section for a card-authorisation API (illustrative)

An authorisation API approves or declines card payments.

Availability arithmetic: a 30-day month has 30 x 24 x 60 = 43,200 minutes, and 0.05% of that is 21.6 minutes of allowed failure (the error budget, the amount of failure the SLO permits). The NFR counts requests but the budget counts minutes, which is only a fair conversion if traffic is spread evenly across the month: then failing 0.05% of requests is like being fully down 0.05% of the time. If traffic is uneven, an outage at peak burns more of the request budget than the same minutes at 3 a.m.

Constraints, listed separately

A constraint is a fixed choice that limits the design, rather than a quality bar. Examples: C-01 the service runs on the existing Kubernetes platform (the company's shared system for running containerised services); C-02 no new third-party payment processor without security approval. Each has an owner and a source.

Conflicts and priorities

State the tensions. NFR-05 (audit every access) can fight NFR-01 (latency). Decision: write audit events to a durable queue asynchronously (a queue that keeps messages safely stored until a separate worker writes them to the audit store), so P99 holds because the request no longer waits for the slower audit write, and accept a short delay before an event appears. Record it as a decision referencing both IDs.

Keeping them visible

• Decision records list which NFR IDs drive them.
• The pull request template asks which NFR IDs the change touches.
• Tests and dashboards carry the ID in their names, so a failure points to the requirement.
• A load test that fails the build turns NFR-01 from a wish into a gate: if P99 rises above 400 ms, the change cannot merge.
• Review the table at each design review, and retire or change requirements through a decision, not by silence.

Pitfalls

• Adjectives ("fast", "secure") with no number.
• A target with no measurement point, so two teams measure differently.
• Forty requirements nobody reads. Keep the few that actually shape the design.
• No owner, so nobody notices when a target is missed.

Direct answer

I annotate the diagram with a small, fixed set of fields on a fixed place: owner as a badge on each box, contract as a link ID on each arrow, and the numbers (latency budget, throughput, error rate) as a short one-line label per arrow. Anything beyond that goes in a table under the diagram, and the numbers are generated from monitoring and contract files so they carry an "as of" date and do not rot.

The conventions I would standardise

• Node (a service box): name from the service catalog, plus a badge with the owning team, for example pricing-api | team: pricing.
• Edge (an arrow): one line, always in the same order: contract | p95 budget | rate | error-rate target, for example pricing-v2 | p95 150 ms | 300 rps | err < 0.1%. (p95 means the 95th percentile: 95 percent of requests are faster than this. rps means requests per second. The last field is the highest acceptable share of failed requests, 0.1 percent here. It is a per-request target, not the SRE "error budget", which is the total failure allowance over a period, derived from a reliability target.)
• Colour is reserved for one meaning, health against target (green, amber, red), never for teams.
• A legend on every diagram, and an "as of" date.
• Limit: about 12 boxes and one annotation line per arrow; more goes into a table or a separate diagram.
• Contract means a link to the API specification (for example an OpenAPI document, a machine-readable description of an HTTP API's endpoints and message shapes) and its version, not prose.

Component-diagram tutorial box

pricing-api (owner: pricing team, contract: pricing-v2 OpenAPI spec, p95 budget 150 ms). Someone reading the box knows what it is, whom to page, which interface to read, and how slow it is allowed to be.

Latency budgets on the critical path

The critical path is the longest chain of calls the user waits for. Steps that run in parallel count as the slowest of them. Illustrative checkout with an end-to-end p95 target of 800 ms:

50 + 100 + 150 + 300 = 600 ms, leaving 200 ms (25 percent) of headroom under 800 ms. Adding percentiles is an allocation rule, not exact statistics, and it is conservative only for calls in series. For the parallel pair the larger budget slightly understates the risk: if pricing and inventory were independent and each met its own p95, both would be within budget only about 90 percent of the time (0.95 x 0.95 = 0.9025), and reaching 95 percent for the pair would need each side at about its 97.5th percentile (0.95 ** 0.5 = 0.9747). That is one more reason to keep the 200 ms of headroom. The p95 of a chain is not the sum of each step's p95: a request is rarely unlucky in every step at once, so the true combined p95 is usually lower than the sum, but correlated slowness (for example a busy database slowing several steps together) can break that. So I treat the sum as a budget to allocate and keep headroom instead of budgeting to the last millisecond.

Instrumentation placement

Put a trace span (a timed record of one operation, from distributed tracing) at each service entry and around each outbound client call, on the critical path only. Then the diagram's numbers come from the measured span durations, and the difference between a caller's client span and the callee's server span reveals network or queueing time. For example, if checkout's client span around the call to payments lasts 340 ms but payments' own server span lasts 290 ms, the other 50 ms went to the network, connection setup or waiting in a queue before payments started work, and that 50 ms is invisible if only one side is measured.

Trade-offs and pitfalls

• Hand-typed numbers go stale; generate annotations from the monitoring configuration and contracts, or show them with a date.
• Annotating every arrow makes the diagram unreadable: annotate the critical path and the arrows that have a service-level objective, and leave the rest. (A service-level objective, SLO, is the reliability target a team commits to, such as 99.9 percent of requests succeeding.)
• Throughput and error rate are observed values, while budgets are targets. Label which is which, otherwise readers cannot tell "allowed" from "actual".

Direct answer

"You can, and for a small start it is often right. Containers behind a load balancer solve one thing: running stateless code (code that keeps no important data of its own, so any copy can serve any request) and spreading requests across copies. The rest of the bill, which decides cost, risk and time, is everything that does not fit in that sentence: where data lives, how we release safely, what happens when a machine or a zone fails, and who is paged." The one-page answer maps each of those gaps to money, exposure and schedule.

The one page

Worked example: why the weakest part sets availability (illustrative, assumes independent failures)

Availability is the share of time a part is working. "Independent" means one failing does not make the other more likely to fail (for instance they are not on the same power feed). For reference, 99.9% availability allows 0.001 x 8,760 hours in a year, about 8.8 hours of downtime.

• Two app instances, each up 99.5% of the time (down 0.5% = 0.005). The app tier fails only when both are down at once, and with independent failures that happens 0.005 x 0.005 = 0.000025 of the time. So app tier availability is 1 - (0.005 x 0.005) = 1 - 0.000025 = 0.999975, or 99.9975%.
• One database, up 99.9%. Everything must be up together, so multiply: 0.999975 x 0.999 = 0.998975, about 99.90%. That is 0.001025 x 8,760 = about 9 hours of downtime a year.
• Add a standby database (a second copy in another availability zone, meaning a separate data centre within the region, that takes over if the first fails). The data tier fails only if both copies are down: 1 - (0.001 x 0.001) = 0.999999. Overall: 0.999975 x 0.999999 = about 0.999974, roughly 14 minutes a year (0.000026 x 8,760 hours = 0.23 hours).
• Real systems are worse: failover (the switch to the standby) takes time and failures are not fully independent. Treat these as ceilings, not promises.

Cost in plain numbers (illustrative): if capacity is sized for a peak that is 2.5 times the average, about 60% of it sits idle off-peak, so we pay for 100 to use 40 unless autoscaling (adding and removing instances automatically with load) or right-sizing (choosing instance sizes that match real usage) trims it. A standby database roughly doubles that one component's running cost, which is the price of removing the 9 hour ceiling.

Recommendation

Start with containers behind a load balancer plus the three cheap additions: a managed database with a standby, automated deployments with rollback, and basic alerts. Delay heavier machinery until a measured need, such as an availability target we are missing.

Heavier machinery, rarely needed at the start: multi-region means running the whole system in more than one geographic region to survive a regional outage, and a service mesh is an extra network layer that manages service-to-service traffic, security and retries. Both add cost and operating burden, so we adopt them only on a measured need.

Trade-offs and pitfalls

• Do not oversell complexity. "It's complicated" is not an answer.
• Do not undersell it either: "just containers" ignores the database and the on-call people.

Direct answer

An executive architecture diagram shows the system as its users and business would describe it: who uses it, the handful of major capabilities, what external systems it depends on, and where the risks and costs sit. It omits protocols, ports, libraries, class names and anything that only changes an engineer's decision. The narrative is a short paragraph that says what the system does for customers, how big it is, the main risk and the decision needed.

Element list for the diagram

1. Users and actors: customers, staff, partner systems, named in their own words.
2. The system boundary (the line separating your product from the outside world): one labelled box for the product.
3. Five to eight major capabilities or building blocks (for example Catalogue, Orders, Payments), not individual microservices (small, separately deployed services).
4. External dependencies (outside services the system relies on): payment provider, identity provider, data sources.
5. Data flow direction: labelled arrows in business terms ("places order", "sends receipt").
6. Boundaries that matter to the business: regions, regulated data, third-party ownership.
7. A risk or cost marker: one colour or icon on the part that is fragile or expensive.
8. Legend and date: what a box and arrow mean, and when it was checked.

What I deliberately omit

Protocols and ports, cloud service names, database engines, class or component detail, deployment scripts, internal team names. If a viewer would need a glossary, it has too much.

Worked example: order service one-slide summary

Title: "Orders: turning a customer's basket into a paid, shipped order." Diagram: Customer, then Orders (the boxes Basket, Checkout, Fulfilment), connected to Payment provider and Warehouse system. One box, Checkout, is flagged amber: "single point of failure until August" (one part whose failure stops the whole flow). Below it, three lines: user value ("customers can buy in three taps"), main risk (checkout has no fallback), two operational KPIs (key performance indicators, the few numbers that show whether the system is healthy): checkout success rate and delivery-on-time rate.

Two more cases: an ML service and a one-page sales summary

• ML recommendation service (a machine learning model that suggests products; it learns from past shoppers' clicks and purchases): the same shape, showing Shopper, Recommendations (a box labelled "suggests products using past behaviour") and the data it learns from ("past clicks and purchases"), with a KPI such as click-through, the share of shown suggestions that get clicked. For example, 1,000 suggestions shown and 50 clicked is 50/1,000 = 5% click-through. Model architecture stays in the appendix.
• A one-page summary for a salesperson, or for a colleague who will pass it on: user value first, major components, key risks, and two operational KPIs the listener can repeat accurately.

Pitfalls

Drawing the engineering diagram smaller; forgetting to say what decision the page supports; using colour without a legend.