02 — Architectural Mastery

Goal: make foundational decisions deliberately — before they become expensive — and bootstrap scalable apps (React / Next.js 15 App Router / strict TS) with a repeatable blueprint.

The core principle: Architecture is the set of decisions that are expensive to reverse. Everything else is implementation detail. The job is to identify those decisions, defer the reversible ones, and make the irreversible ones with a written rationale.

Part 1 — Mental models (think in these before any decision)

1.1 The reversal-cost lattice

Every decision has a reversal cost. Classify before choosing:

Rule: never spend architectural ceremony on cheap-to-reverse decisions (YAGNI lives here); spend it on expensive ones. If a decision is expensive, write the ADR (01).

1.2 Conway's law, exploited

"Organizations design systems that mirror their communication structure."

The architecture will match your team topology whether you like it or not. Design for the team you have and the growth you expect: if 3 frontend engineers own one app, a modular monolith with clear boundaries beats micro-frontends. If 4 teams must ship independently to one product surface, boundaries (module federation / MFEs / package isolation) become a team problem, not a tech preference. Never adopt micro-frontends for a team that fits one repo — you are buying coordination costs you don't have.

1.3 Architecture is a trade-off lattice, not a ladder

Every "best practice" is a trade against something. Use the lattice:

1.4 The three-box mental model (before writing any code)

1. Domain box: What is this system fundamentally? (A dashboard, a checkout, a collaboration tool…) — this decides state shape and data model.
2. Delivery box: How does code reach users? (CDN, edge, regions, offline/PWA needs) — decides rendering and caching.
3. Evolution box: What will change in 18 months? (New team members? Mobile app consuming the same API? Multi-tenancy?) — decides boundaries and contracts. Decide each box independently, then compose. Most bad architecture is mixing the three (e.g., choosing a data-fetching library because of a delivery concern).

1.5 The decision matrix (ask before every foundational call)

Score options 1–5 per row, weight the rows that matter to your context:

Rule: if the matrix is within 10% and you have no data, pick the more boring option — boring scales in hiring, debugging, and longevity. Never pick an architecture to impress an interviewer; pick one that survives a team change.

Part 2 — The bootstrap blueprint (step-by-step)

Step 0 — Contract the problem (30–60 min, written)

• One-paragraph purpose; the primary user journey; the success metric (LCP/INP budget, conversion, DAU — pick one).
• Write the ADR-0: scope, non-goals, team size, 18-month evolution guess (box 3). Everything downstream references this.

Step 1 — Set up the monorepo (pnpm workspaces or Turborepo)

• One repo, clear package boundaries: apps/web (Next.js), packages/ui (design system), packages/config (shared tsconfig/eslint), packages/api-client (generated client), packages/utils.
• Root tsconfig strictness baseline inherited everywhere (see Step 4).
• AI-assisted: generate the workspace skeleton with Claude Code in a sandbox — prompt: "Scaffold a pnpm monorepo with Turborepo containing a Next.js 15 app router app and three packages (ui, config, api-client) with strict TS." Review every generated file before committing — the AI is a fast typist, not an architect.

Step 2 — Next.js 15 App Router foundations

• Route groups for layout scopes: (marketing) (static, SSG), (app) (authenticated, dynamic), (auth) (login flows) — each with its own layout and rendering strategy.
• Server-first by default: data fetching in Server Components; 'use client' only at interaction boundaries. If a component doesn't handle events or hold state, it should be a server component.
• Streaming: use loading.tsx + Suspense boundaries per route segment — never block the shell.
• Caching semantics — know them precisely: fetch caching defaults, revalidateTag/revalidatePath for ISR, and the staleTimes client router cache in Next 15. Document the cache map per data type in ADR-1.
• Server Actions for mutations inside the app; keep them thin (validate → call service → revalidate) and never trust client input.

Step 3 — Define the data contract FIRST (contract-first)

• Backend publishes an OpenAPI spec; frontend generates the typed client (openapi-typescript + a thin fetch wrapper, or orval). No handwritten API types — they drift.
• Runtime validation at the boundary only (zod on server action inputs / route handlers); everywhere else types are trusted because they were generated.
• Error model agreed with backend: stable error codes (NOT_FOUND, RATE_LIMITED…), one ApiError shape, typed per endpoint. QA and backend sign off on this document (this is 01 influence in action).

Step 4 — Strict TypeScript, zero-exception

// packages/config/tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "moduleDetection": "force",
    "skipLibCheck": false
  }
}

• noUncheckedIndexedAccess alone removes an entire class of "silly bugs" (04). Add any-ban in ESLint (@typescript-eslint/no-explicit-any: error), with a 0-tolerance policy: a suppressed rule requires a written comment with a ticket.

Step 5 — Data layer (server state discipline)

• One server-state library (TanStack Query) or server components + router cache — not both doing the same job in the same area.
• Query keys as a typed factory (queryKeys.user.profile(id)) — stale keys are the #1 source of "data not refreshing" bugs.
• Mutations: optimistic updates with snapshot rollback (see the pattern in the Scale & UX section) or invalidation — decide per mutation and write it down.

Step 6 — Design system seed (don't boil the ocean)

• Token-first (colors/spacing/type as CSS variables), one Button/Input/Modal/Dialog accessible by default, Storybook, and a governance note (when to add vs compose). Never build 40 components before the product has 3 screens — YAGNI is a cost rule, not a purity rule.

Step 7 — Observability from day one (not week 12)

• Error tracking with source maps; RUM for Web Vitals (INP/LCP/CLS); one analytics event spec (event, properties typed). You cannot architect what you cannot measure — the first "performance work" is installing the meter.

Step 8 — CI as the gate

• Lint → typecheck → unit tests → build → e2e (smoke on critical journeys) → bundle-size check (size-limit) → deploy preview. The pipeline is the enforcer of everything in 04.

Step 9 — Rollout & release discipline

• Feature flags from the start (even a local one) so any release is reversible; canary deploys; a written rollback drill. Reversibility is an architectural property — cheap reversals let you take bigger swings.

Part 3 — AI-assisted architecture (make it a force multiplier)

• Use Claude Code/Copilot for research and skeletons, never for the decision. Prompt for: "Compare [options] for [context]; list trade-offs with sources; produce a decision matrix" — then you apply judgment.
• Generate the ADR draft from your decision, then edit — the discipline is the artifact, not the prose.
• Ask for the counter-argument: after choosing, prompt "argue against this decision as a skeptical principal engineer" — free red teaming before you commit.
• Sandbox spikes: generate a spike implementation in a throwaway branch to validate an unknown (e.g., "does module federation work with our auth flow?") — timebox to a day, then delete or formalize.

✅ The architecture checklist (before any foundational commit)

• Reversal cost classified; expensive decisions have an ADR
• Three-box model answered (domain / delivery / evolution) in writing
• Decision matrix scored for any framework/library choice ≥ moderate reversal cost
• Team topology considered (Conway's law) — architecture fits the org
• Data contract-first: OpenAPI → generated typed client; error model agreed
• Strict TS baseline on; any policy enforced in CI
• Rendering strategy per route group documented (SSG/ISR/SSR/CSR)
• Observability (errors + RUM) installed before feature work
• Feature flags + rollback drill exist
• The boring option won unless data said otherwise

→ Next: 03 — Flawless Execution · Back: 01 — Visibility & Influence