Skip to main content

Draw the Box Diagram

What This Concept Is​

The high-level diagram is a single picture that a reviewer can read in thirty seconds and see:

  • the API surface (what clients call)
  • the components (named boxes that own responsibilities)
  • the data flow (arrows showing request and response paths, plus background flows)
  • the stores (databases, caches, object stores, queues)
  • the boundaries (datacenter, region, trust zone)

It is not a UML class diagram. It is not a deployment topology. It is a shared map for the rest of the conversation. Its job is to make every other question in the session answerable with "here, in this box, via this arrow".

A competent high-level diagram has 6-12 boxes. Fewer and you have not actually decomposed; more and you are designing implementation details too early.

The diagram's job is to pick a specific level of abstraction and stay there. Simon Brown's C4 model calls this the Container level: each box is something independently deployable or runnable (a service, a database, a cache, a queue broker). A mix of containers with classes or files on the same diagram is the most common cause of "this design feels unreadable" in a review -- the reader spends cognitive budget deciding what kind of thing each box is before they can follow the flow. Fundamentals-style component-based thinking says the same thing in different words: components are the unit of reasoning for an architect.

Why It Matters Here​

The box diagram is the artifact every later cluster refers to.

  • Cluster 2 storage and caching choices attach specific boxes to it.
  • Cluster 3 deep dive picks one box and zooms in.
  • Cluster 4 stress test walks the arrows and asks "what if this one times out?"
  • Cluster 5 trade-offs refer to decisions made while drawing the diagram ("why a queue here, not a direct call?").

If the diagram is ambiguous, every later question is ambiguous.

Concrete Example: URL Shortener​

Classic high-level diagram for a URL shortener:

  ┌────────┐
  │ Client │
  └───┬────┘
      │ HTTPS
      ▼
  ┌──────────────┐         ┌───────────────┐
  │   CDN / DNS  │ ──────▶ │ Load Balancer │
  └──────────────┘         └───────┬───────┘
                                   │
                 ┌─────────────────┼──────────────────┐
                 ▼                 ▼                  ▼
         ┌──────────────┐  ┌────────────────┐  ┌───────────────┐
         │  Write API   │  │   Redirect     │  │   Analytics   │
         │  (POST /u)   │  │   Service      │  │   Ingester    │
         │  shortener   │  │   (GET /:code) │  │               │
         └──────┬───────┘  └───────┬────────┘  └───────┬───────┘
                │                  │                   │
                ▼                  ▼                   ▼
           ┌─────────┐       ┌──────────┐        ┌──────────┐
           │ ID Gen  │       │  Cache   │        │  Kafka   │
           │ Service │       │ (Redis)  │        │  topic   │
           └────┬────┘       └────┬─────┘        └────┬─────┘
                │                 │ miss              │
                ▼                 ▼                   ▼
           ┌─────────────────────────────┐     ┌──────────────┐
           │   URL Store (Primary DB)    │     │  Analytics   │
           │   key: code, value: url     │     │  Warehouse   │
           └─────────────────────────────┘     └──────────────┘

Things to notice about this sketch:

  • Named API surface: POST /u (create) and GET /:code (redirect). Those are the only two endpoints clients see.
  • Read and write are drawn as separate services, even if they share a deployment. The reader sees that the read path is optimized for latency and the write path for correctness.
  • The cache sits in front of the DB only on the read path. The write path updates the DB, then invalidates or populates the cache explicitly.
  • Analytics is async (Kafka), so it cannot slow down the user-visible hot path.
  • The ID generator is its own box because uniqueness at scale is a hard part. The box makes it explicit.

Alternative: a social feed diagram would add a fan-out worker, a per-user timeline store, and a ranking service, because those are its hard parts.

Concrete Example 2: Chat System​

  Mobile/Web client ─▶ Global LB (anycast)
                         │
                         ▼
              Regional LB (L7, TLS term)
                         │
          ┌──────────────┼──────────────────────┐
          ▼              ▼                      ▼
      Connection      Send API            Presence Svc
      Gateway         (REST/gRPC)         (in-memory)
      (WebSocket)         │                      │
          │               ▼                      ▼
          │          Message Store         Presence KV
          │          (wide-column,         (Redis)
          │          partition: conv_id)
          │               │
          │               ▼
          │          Pub/Sub (Kafka)
          │               │
          ├───────────────┘ async fanout
          ▼
      Push Notif Svc ─▶ APNs / FCM

Boxes earn their place as follows:

  • Connection Gateway is its own box because WebSocket lifecycle and reconnection are fundamentally different from stateless HTTP.
  • Send API is separate so that send-path correctness (ordering, idempotency) can evolve independently from the connection tier.
  • Presence gets its own box and store because its access pattern (ephemeral, high-write, memory-resident) does not match the durable message path.
  • Kafka is drawn on the diagram because async fan-out is the system shape for chat at scale; hiding it "inside the backend" would let the reviewer assume synchronous delivery, which is wrong.

Compare-and-contrast: the URL shortener has no async fan-out in the hot path; chat's entire architecture is built around it. The diagrams should look different because the systems are different, not because of stylistic preference.

Common Confusion / Misconceptions​

"Boxes are free; the more the better." No. Every box is a failure domain and a deployment unit. Five well-chosen boxes beat fifteen arbitrary ones. A reviewer will ask about every box you draw.

"The diagram is the design." The diagram is the shared model. The design is the set of written decisions about what happens in each box and on each arrow.

"I will add arrows as I go." Draw every arrow on the request path and label it (sync call, async event, fire-and-forget). An un-drawn arrow is an unstated dependency and a reviewer will find it.

"Monolith is boring; I will draw microservices." If the problem says "one team, 10 K QPS, 500 GB data", draw a monolith with modules. The reviewer is checking whether you justify boxes, not whether you name them impressively.

"Mixing abstraction levels is fine." It isn't. One diagram = one level (C4 Container level is the right fit for an interview). If you need to show internals, zoom into a single box on a second diagram -- do not cram both levels onto one picture.

How To Use It​

Diagram-drawing protocol:

  1. Put the client on the left and the data stores on the right. Arrows flow left-to-right on the hot path.
  2. Draw the API surface first as a column of endpoints on the left edge, not as interior boxes. This forces you to commit to the contract.
  3. Name each box with a noun and a role: "ID Gen Service", "Feed Ranker", not "Service 1".
  4. Distinguish sync from async arrows: solid for sync request/response, dashed or open-arrow for async events.
  5. Mark trust/region boundaries with a dotted rectangle. It will matter in Cluster 4.
  6. Keep it 6-12 boxes. If you need more, collapse siblings into a single labeled box and decompose later in Cluster 3.

Commit the diagram early. Do not keep erasing; annotate instead.

Transfer / Where This Shows Up Later​

  • Cluster 3 picks one of these boxes to decompose. The five-question decomposition template assumes the box is clearly named here.
  • Cluster 4 walks the arrows looking for failure and bottleneck. An un-drawn arrow is an un-analyzed failure mode.
  • S8M2 (microservices) turns each box into a service boundary decision -- which boxes become separate deployables, which become modules inside one deployable.
  • S8M5 (technical leadership) uses this diagram as the opening image of architecture reviews and ADRs; Fundamentals' "diagram guidelines" chapter is the standard format.
  • S9 (cloud + DevOps) maps each box onto concrete cloud services (ECS/EKS task, managed DB, managed cache, managed queue).
  • S10 capstone + interviews: the box diagram is the artifact you are judged on visually. "Could I understand your design in 30 seconds from the board?" is a yes/no gate at staff+ interviews.

Check Yourself​

  1. If your diagram has 20 boxes, what are the three candidates to merge back?
  2. Can you point to each functional requirement from Cluster 1 and say which box owns it?
  3. Where on the diagram does a write become durable? Where does a read become user-visible?
  4. If a reviewer asked "what abstraction level is this at?" -- could you answer in one word?

Mini Drill or Application​

Pick two prompts from your framing drills (Cluster 1 concept 1 mini drill) and draw a high-level diagram in under ten minutes each:

  1. Rate limiter for an API gateway.
  2. Real-time stock price feed.

For each diagram, annotate:

  • the API surface (endpoints or protocols)
  • each box with a one-line responsibility
  • every sync vs async arrow
  • the region/trust boundary

Then critique your own diagram: which box would you delete if the interviewer gave you half the scale? Which would you split if they gave you 10×?

Read This Only If Stuck​