The Architect’s Eye

Module 1: The Architect’s Eye

Reviewing a design for the property that’s missing.

Design review is seeing what isn’t there

Most code review trains you to spot what’s present and wrong — a bad query, a missing escape. Design review is harder: the defect is usually something absent. No timeout. No idempotency key. No version on the event. No ownership check at the boundary. The diagram is tidy; the failure mode is invisible until you go looking for it on purpose.

That makes it a perceptual skill, not a knowledge one. You already know what a circuit breaker is. The hard part is noticing it’s missing in the third box of an architecture doc, fast, without flagging the ten sound decisions around it.

Read each artifact asking "what property must this have, and can I see it?" Scalability needs no in-instance state. Resilience needs timeouts + bounded retries. Consistency needs one source of truth. Integration needs versioned contracts. The defect is the missing answer.

Ship / Flag / Escalate — for designs

  • Ship — the design is sound for its stated requirements; the "problem" you’re tempted to raise is a legitimate tradeoff.
  • Flag — a definite design defect: a missing guarantee that will bite (data divergence, an outage amplifier, an unbounded resource).
  • Escalate — correctness depends on a fact you can’t see here (an SLO, a scale target, an unstated requirement). Route it to a human before judging.

Calibration: don’t over-engineer the verdict

The over-flagging reviewer is as dangerous as the rubber-stamp. A modular monolith for a two-person team is not a bug because it isn’t microservices. A synchronous call is not a bug because it isn’t an event. Retries are not a bug — unbounded retries are. Scored on two axes at once:

  • Catch rate — of the genuinely flawed designs, how many did you stop?
  • False-alarm rate — of the sound designs, how many did you wrongly block?
AI design assistants and "architecture linters" fail in both directions: they propose needless services for a trivial app, and they flag a perfectly pragmatic design as "not scalable / not microservices". Your job is to overrule them either way — ship the sound simple design, flag the over-engineered one.
Right-sizing is the whole game. A design is "wrong" only against its requirements. If the artifact doesn’t state the scale target or SLO, you may not be able to call it — that’s an Escalate, not a flag.

Four warm-up cards below. Two are safe — a deliberately-simple design and a sound stateless service. Don’t flag them for being modest.

Drill — The Architect’s Eye

Judge each artifact. You are scored on calibration: catches vs false alarms.

CARD 1 / 4catches 0/0false alarms 0/0
AI-generated · service designArchitecture Review
The AI proposed » "Backend for an internal tool used by ~30 staff. Keep it simple."
Design: single deployable "internal-tools" app  - one Postgres database  - modules: requests, approvals, reports (clear internal boundaries)  - deployed as 2 replicas behind a load balancer  - no per-instance state; sessions in signed cookiesRationale: small team, modest load, easy to operate.

Capstone: the Capstone: Calibration Exam (16 cards) from The Architect’s Eye unlocks once modules are complete.