5 exercises on describing architecture, data flow, failure handling, and hedging assumptions with appropriate precision in a design doc.
Key patterns
Name every component, protocol, and data format — avoid "some kind of" or "a system".
Describe data flow as: actor → action → mechanism → consumer → latency target.
State failure handling concretely: trigger, retry policy, fallback, user impact.
Hedge with named assumptions and thresholds: "This assumes X; if Y, we will Z".
0 / 5 completed
1 / 5
You are opening the Proposed Solution section of a design doc. Which version best describes the architecture with appropriate precision?
A Proposed Solution section must name components, describe data flow, and justify the structure.
Option B does this: it names the three services, states the communication mechanism (Kafka, topic orders.v1), and names the benefit (independent scaling). That gives reviewers something concrete to evaluate.
Use noun phrases for components: "Order Intake service", "event bus", "cache layer".
Name the protocol or mechanism: "via Kafka", "over gRPC", "through a REST gateway".
State the architectural benefit: "allowing X to scale independently", "decoupling Y from Z".
Option A hedges with "some kind of" and "possibly" — unacceptable in a design doc. Option C is name-dropping without substance. Option D is a red flag ("rewrite everything") with no specifics.
2 / 5
Which sentence best describes a data flow between components in a design doc?
Data-flow descriptions must name the actors, the message, the mechanism, and the timing constraint.
Option C does all four: actor (browser), action (POST CreateOrder), mechanism (API Gateway → Kafka topic), consumer (Fulfilment service), and SLO (200ms). Reviewers can trace exactly what happens and where failures could occur.
Prefer active voice with a named subject: "The browser POSTs", not "data is sent".
Name the event or payload type: OrderCreated, UserRegistered.
Include the latency target or SLO where relevant.
Use arrows or prose consistently — mix them when needed: "A → B via C".
Options A and D are passive and vague. Option B is too short to be useful — it stops before naming any mechanism.
3 / 5
A section describes how your proposed solution handles failure. Which version is most professional?
Failure handling in a design doc must be concrete: trigger, mechanism, retry policy, fallback.
Option C names the failure trigger (payment-provider timeout), the retry strategy (3 retries with exponential back-off at 1/2/4s), the fallback (orders.dlq), and the user experience (error page with reference). That is a complete failure model.
Standard patterns to name: circuit breaker, retry with exponential back-off, dead-letter queue, idempotency key, bulkhead.
Quantify back-off: "1s, 2s, 4s" is far more useful than "gradually increasing delays".
Always state user impact: what does the end user see or experience?
Option A is vague ("gracefully", "retry" with no bounds). Option B is a placeholder, not a design. Option D dismisses the concern entirely — a red flag in any review.
4 / 5
You are adding a hedging clause to your proposed solution. Which phrasing is most appropriate for a design doc?
Hedging in a design doc means stating your assumptions explicitly, with a trigger for re-evaluation.
Option C is the correct form: it names the assumption (read traffic <10,000 RPS), the threshold that would invalidate it, and where the mitigation lives (Section 6). This shows that the author has thought about limits without pretending to solve every future problem.
Native hedging phrases: "This assumes that…", "provided that…", "subject to…", "in the event that X, we will Y".
Always name what is assumed, when it breaks, and where to look for the contingency.
Contrast with false hedging: "might work" or "should be okay" signals unfinished thinking.
Options A and D express doubt without grounding it. Option B is not a hedge at all — it defers design work entirely, which undermines the whole doc.
5 / 5
A colleague asks you to add more detail to your component diagram description in prose. Which version is the clearest improvement?
Prose descriptions of architecture diagrams must enumerate the layers, name the technologies, and state the relationships.
Option C walks the reader through the diagram systematically: it names three numbered layers, the technology at each layer (React SPA, GraphQL API, PostgreSQL), the protocol (HTTPS), and a nuance about the database (read replica for analytics). A reader who cannot see the diagram still understands the architecture.
Structure prose descriptions as: "Layer 1 → Layer 2 via protocol, which → Layer 3 for purpose".
Always name the protocol between components (HTTPS, gRPC, TCP).
Note any variants: primary vs. replica, hot path vs. cold path.
Options A and B are placeholder sentences. Option D outsources understanding to an attachment — fine as a supplement, but the text must stand alone.