Codebase Architecture

Decide a TypeScript codebase's structure, improve it where change has become expensive, and make it hold. The target is a codebase a reader can hold in their head: few surfaces, one canonical way to do each job, and behaviour where you would first look for it.

• IS: folder structures, module contracts, middleware pipelines, frontend/backend boundaries; architecture briefs; domain language and decision records; domain-informed deepening; guardrail tooling, CI gates, and agent wayfinding.
• IS NOT: scaffolding a new repo (scaffold-nextjs for a Next.js turborepo, scaffold-cli for a TypeScript CLI), multi-tenant domain/isolation/routing (multi-tenant-architecture), the content of AGENTS.md itself (agents-md), a diff-scoped cleanup pass (tidy), or structural review of a local diff (pr-reviewer).

Contents

• Modes
• References
• Design mode (new codebase)
• Deepen mode (existing codebase)
• Harden mode (make it stick)
• Validation loop
• Output template
• Excuses
• Gotchas