Scale The Codebase

Scale by making ownership clearer, not by adding generic layers before they are needed.

On this page

1
Start flat when the module is small
A feature with four or fewer files can use responsibility-named files such as actions.ts, queries.ts, persistence.ts, and schemas.ts.
2
Split by responsibility when density grows
Once a module mixes reads, writes, services, persistence, schemas, and UI, split into named folders for the responsibilities that actually exist.
3
Split by sub-domain for independent systems
If a module contains separate systems, organize by sub-domain first, then actions, queries, services, persistence, and schemas inside that sub-domain.
4
Protect high-risk boundaries
Auth, billing, webhooks, admin actions, file uploads, jobs, and schema changes need explicit validation, idempotency, observability, and focused tests.
5
Document operational changes
New env vars, provider setup, cron dependencies, billing catalog changes, and data repair steps should be documented with the feature change.