codebase-architecture

Topics in the source

• Codebase Architecture
• Contents
• Modes
• References
• Design mode (new codebase)
• Deepen mode (existing codebase)
• Harden mode (make it stick)
• Validation loop

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). Modes References Design mode (new codebase) Deepen mode (existing codebase) Harden mode (make it stick) Validation loop Output template Excuses Gotchas Pick by the problem, not by the artifact. | Mode | You are here when | Output | |------|-------------------|--------| | Design | Starting a new app, service, or surface, and the structure is not decided yet | An architecture brief | | Deepen | The co

This is an excerpt. Refer to the complete source and its current requirements.