High-Level Design vs Low-Level Design

A high-level design answers "what are the moving parts, and how does data get between them". Its vocabulary is components and services, the data stores each one owns, the queues and streams that connect them asynchronously, the network and trust boundaries they sit inside, and the major flows — the two or three paths that carry most of the system's traffic and value. The boundaries deserve particular attention, because a boundary is where the properties change: a call that crosses a process boundary can fail in ways an in-process call cannot, a call that crosses a trust boundary needs authentication and authorization, and a call that crosses a network boundary needs a timeout. Marking them is what makes the diagram say something rather than merely arrange things. What does not belong is anything about the inside of a box: class names, method signatures, schema columns, algorithms. Not because those are unimportant, but because a reader at this level is asking a different question, and mixing the two produces a diagram that is too detailed to see the shape and too incomplete to implement from. A good test is whether the design still reads correctly if one component's internals were replaced entirely — if it does, the level is right.

A high-level design, written out

  [browser] --https--> (edge/CDN)
                          |
                    == trust boundary ==
                          v
                     (api gateway) --sync--> (orders svc)
                                                 |  owns
                                                 v
                                             [orders db]
                                                 |
                          (orders svc) --async--> {events}
                                                    |
                                             (search indexer)
                                                    |  owns
                                                    v
                                              [search index]

  Major flows: 1) place an order  2) search orders

A low-level design answers "how is one component actually built". Its vocabulary is modules and their boundaries, the classes and interfaces inside them, the database schema with its columns, keys, indexes and constraints, the state machines that govern how an entity changes, the algorithms chosen for the parts where the choice matters, and the internal APIs one module offers another. Its scope is deliberately one component — a low-level design that spans three services has drifted into being a poor high-level design. Two elements carry more weight than the rest. The schema, because it outlives the code around it and because constraints written there are enforced against every future writer, which is the difference between a rule and a hope. And the state machine, because most real-world defects are states nobody enumerated: a listed set of states and permitted transitions turns "what happens if the payment succeeds after the hold expired" from an open question into either a transition on the diagram or a gap you can see. The test for the right level here is implementability — a reader who knows the language and the codebase should be able to write the component from it without asking a design question, and if they cannot, the missing piece belongs in the document.

-- schema: the part that outlives the code
CREATE TABLE holds (
  seat_id    uuid PRIMARY KEY,
  buyer_id   uuid        NOT NULL REFERENCES buyers,
  state      text        NOT NULL,
  expires_at timestamptz NOT NULL,
  CHECK (state IN ('held', 'converting', 'released'))
);
CREATE INDEX holds_expiry ON holds (expires_at)
  WHERE state = 'held';   -- partial: only live rows

-- states: held -> converting -> (booked | released)
--         held -> released (expiry or cancel)

The skill is not knowing what belongs at each level — it is descending deliberately and announcing the move. A design conversation naturally slides downward, because concrete details are easier to discuss than abstract ones and everyone has an opinion about a column name. The result is a mixed document: three services sketched at cartoon depth alongside one table's exact indexes, which is too vague to evaluate as an architecture and too incomplete to build from. The discipline has three parts. Descend on purpose: finish the level you are on, say "let me go a level down into the fetch path", and come back up when that path is done. Keep one level per artefact, so a high-level diagram never grows a schema and a component design never grows a network topology — if a detail is needed for the higher level to make sense, it is usually a boundary or a data-ownership fact, both of which are legitimately high-level. And carry consistency between levels: every component named at the high level should have a low-level design or an explicit note that it does not need one, and every store or queue in a low-level design should appear on the high-level diagram. That last check is the one that catches real problems, because a store appearing at the low level and not the high level usually means a component quietly took a dependency nobody reviewed.

Announcing the move, in a review or an interview

  "That is the high-level shape: gateway, orders
   service, event stream, search indexer. The
   risky part is the indexer, so let me go a
   level down into it."

   ... module boundaries, schema, state machine,
       backfill algorithm ...

  "Coming back up: that changes the high-level
   picture in one way -- the indexer needs its own
   store for checkpoints, so it belongs on the
   diagram."