About This Project

Claude Architect Lab is built the same way it teaches: learn a concept, implement it, document the decision, then write the scenario and questions. This page is that record.

Architecture (current — V0.1)

┌───────────────────────┐
│  Browser                 │
│  (Next.js client +        │
│   React Server Components)│
└───────────┬───────────┘
             ▼
┌───────────────────────┐
│  Next.js App Router        │
│  (this app)                 │
│                              │
│  content/ — lessons, quiz    │
│  banks, scenarios; typed and │
│  Zod-validated (tests/)       │
└───────────┬───────────┘
             ▼
┌───────────────────────┐
│  In-memory React state       │
│  (progress + mode —          │
│   session-only, nothing       │
│   stored; ADR-0004)            │
└───────────────────────┘

Planned, not built yet — added when the domain that
teaches it is actually studied:

┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Postgres          │ │ Claude API        │ │ MCP servers        │
│ (Supabase)          │ │ service              │ │                       │
│ — auth + synced      │ │ — Domain 4/5           │ │ — Domain 2 (Tool       │
│ progress, V0.2         │ │ features                │ │ Design & MCP)            │
└────────────────┘ └────────────────┘ └────────────────┘

Full rationale for each decision — including why progress tracking stores nothing at all, not even locally — is in architecture/adr/ in the repo.

Tech stack

Next.js (App Router) + TypeScript
Tailwind CSS v4
Zod — content schema validation
react-markdown — safe prose rendering, no arbitrary code execution
Vitest — content + logic tests
Prisma + Postgres/Supabase (planned, V0.2)
Anthropic TypeScript SDK, server-side only (planned, V0.4+)
Vercel (hosting)

Build roadmap

Domain 1: Agentic Architecture & Orchestration— built
Domain 2: Tool Design & MCP Integration— built
Domain 3: Claude Code Configuration & Workflows— built
Domain 4: Prompt Engineering & Structured Output— built
Domain 5: Context Management & Reliability— built

Source

The full repository — including every ADR, the content schema, and the test suite that validates every question — is public on GitHub.

Build log

V0.1 — Domain 1

Domain 1 (Agentic Architecture & Orchestration) established the lesson template every later domain reuses, and forced three real architecture calls on the project itself: the original MDX content plan turned out to be the wrong fit once the lesson template's blocks were actually written (see ADR-0002); progress tracking first shipped via localStorage instead of waiting on a database and auth provider (ADR-0003); and that decision was then reversed to store nothing about a learner at all — progress is now purely session-live, resetting on reload (ADR-0004). All three changed after starting to build, not before.

V0.2–V0.5 — Domains 2–5 content, pending review

A deliberate, flagged exception to this project's usual process: at the owner's explicit direction, Claude drafted all four remaining domains' lessons and practice questions in one pass — 80 questions and four full lessons, matching Domain 1's template and schema exactly — rather than one domain at a time after being studied. It's live on the site now, passes every automated check (schema validation, structural invariants, type-check, lint, build), and Claude followed up with a fact-check pass against primary sources (MCP spec docs, Claude Code docs, Anthropic API docs) for the specific claims flagged after drafting — one inaccuracy turned up (a retry-code list in the Domain 5 code sample included status codes Anthropic's API doesn't actually document) and was corrected. That still isn't the same thing as the owner's own review, which hasn't happened yet. Until it does, treat Domains 2–5 the way you'd treat a carefully self-checked but still unreviewed draft — see docs/roadmap.md for the full fact-check results, broken down per domain.

[Personal note for the project owner: add your own reflection here per domain — what surprised you, what you'd do differently. That part is more credible coming from you than from a build log.]