The Hitchhiker's Guide to Platform Architecture

A warm-up primer for Phase 7. Read this first. It builds the mental models an architect carries, shows how the runnable labs fit together, and gives you the throughline that turns ten labs into one coherent story you can defend in an architecture interview.

Don't panic. By the end you'll have built — in real, tested, runnable Go — an event bus, a partitioned commit log, the transactional outbox, a saga orchestrator, consistent hashing, an IaC engine, a GitOps reconciler, and an SLO/burn-rate engine. But the deeper goal is the judgment the architect role is hiring for, so each lab pairs the code with the trade-off behind it.

1. The four questions every platform architecture answers

Every distributed platform — Apple's CAD infra or anyone's — is a set of answers to four questions. Phase 7 is organized around them.

1. WHERE ARE THE BOUNDARIES?   how do we split this into services?      pa-01, pa-02
2. HOW DO SERVICES TALK?       sync request/reply vs async events       pa-02, pa-03, pa-04, pa-05
3. WHERE DOES THE DATA LIVE?   partitioning + consistency model         pa-06
4. HOW DO WE SHIP & OPERATE?   IaC, GitOps, SLOs, and decision-making   pa-07, pa-08, pa-09, pa-10

If you can answer those four for a system — with the trade-offs named — you can architect it. The labs make each answer concrete and runnable.

2. The one trade-off that dominates: sync vs async

More than any other choice, synchronous vs asynchronous communication shapes a platform's failure behavior, and architects are tested on it constantly.

SYNC (REST/gRPC, pa-02):   A calls B and waits.
  + simple, immediate answer, easy to reason about.
  - TEMPORAL COUPLING: A is only as available as B; latency compounds
    down the chain; one slow dependency cascades (you need breakers,
    bulkheads, timeouts — gw-06, pa-09).

ASYNC (events/log, pa-03/pa-04):  A emits an event; B consumes when ready.
  + decoupled in time and availability; load-leveling; fan-out; audit log.
  - EVENTUAL CONSISTENCY: ordering, idempotency, duplicate delivery, and
    "where did my event go" become YOUR problems (pa-05).

There is no free lunch — you move complexity, you don't remove it. The architect's job is to put each edge on the right side of that line and own the resulting failure model. Labs pa-03/04/05 build the async side so its costs (delivery semantics, the dual-write trap, sagas) are concrete, not abstract.

3. The distributed-monolith trap (the cardinal sin)

The most common failed "microservices" architecture is a distributed monolith: services that look independent but must deploy together, share a database, or make a synchronous call per request. You've taken a monolith and added network latency, partial failure, and serialization overhead — strictly worse.

The antidotes run through the whole phase:

• Boundaries by capability (bounded contexts), each independently deployable and owning its data (pa-01).
• Contracts that version independently so a producer change doesn't force a lockstep consumer deploy (pa-02).
• Async where you can to break temporal coupling (pa-03/04).
• The outbox so a service owns its data and its events without a shared DB or a dual write (pa-05).
• Fitness functions that fail CI when a cycle or a forbidden dependency sneaks in (pa-10).

pa-01's servicegraph literally detects the structural symptoms (cycles, high coupling) in code.

4. The throughline back to the rest of the book

Phase 7 stands on the consensus and gateway work:

• Reconciliation everywhere. The IaC engine (pa-07), the GitOps reconciler (pa-08), the Kubernetes operator (gw-10), and the xDS control plane (gw-08) are the same level-triggered, idempotent, converge-to-desired-state loop. Once you see it four times, it's a reflex: declare desired state, diff against actual, converge safely.
• Delivery semantics are a consistency problem. at-least-once + idempotent consumers (pa-03/05) is the practical face of the same exactly-once-is-a-myth lesson from gw-05's push delivery.
• Partitioning + quorums (pa-06) is db-17's majority argument and gw-04's subsetting ring, applied to data placement.
• SLOs/error budgets (pa-09) extend gw-11's observability into the reliability-engineering discipline that governs how fast you ship.

You are not learning a new field. You're learning to compose the pieces into a platform and to own the trade-offs.

5. How Phase 7 is built (and how to use it)

Every lab ships real, go test -race-green, stdlib-only Go (builds offline) plus a maintainer-level GUIDE.md, CONCEPTS.md, references.md, docs/{analysis,execution,verification}.md, code-rich steps/, and scripts/verify.sh. Work a lab like this:

1. Read CONCEPTS.md (the why + the 8-part framework).
2. Open GUIDE.md next to src/go/ and read the code it walks you through.
3. Run bash scripts/verify.sh and read the test names — they're the spec.
4. Run the demo CLI to see the headline result.
5. Do the exercises (they're the interview).

Verify the whole phase:

bash pa-00-platform-architecture-overview/verify-all.sh

6. The headline results you can reproduce

7. Suggested path

pa-01 ─▶ pa-02 ─▶ pa-03 ─▶ pa-04 ─▶ pa-05      [the comms + data spine, in order]
                                  │
        ┌──────────────────────────┼──────────────────────────┐
        ▼                          ▼                           ▼
  pa-06 (data)             pa-07 (IaC) ─▶ pa-08 (GitOps)   pa-09 (SLOs)
                                                              │
                                                  pa-10 (architecture in practice)

Now read pa-01's CONCEPTS. The first question every platform answers is "where are the boundaries?" — start there.