Structure Law

Every stack has ONE canonical layout. Repos never invent their own. Structure is settled at intake and recorded in projects — never re-litigated per task.

The structure ladder (pick by project size, once)

There is no single "correct" structure — there is one correct structure per project size. Climb only as far as the project demands:

Rules of the ladder:

• Feature-based is the production default. Related files stay together; features ship and delete as units. Type-based scatters one feature across seven folders — acceptable only below ~30 components.
• Atomic only for reusable component libraries. In a product app it forces "is this a molecule or organism?" debates that produce zero user value.
• Never scaffold a higher rung "for later" — a flat project moves to feature-based when the second real feature lands, not before (ponytail).
• Each feature exports through its own index.ts; nothing deep-imports across features. But no giant root barrels — one index.ts re-exporting the world breaks tree-shaking and creates circular imports.
• Colocate what only one route uses (App Router: _components/ inside the route). Promote to shared/ on second use, never on first.

Intake questions (asked once)

1. Frontend and backend: separate repos or one? (default: one repo, separated apps)
2. Multiple frontends? → Turborepo monorepo. Single app? → plain Next.js.
3. Frontend folder name: frontend/ or product name? (default: apps/<name>)
4. Model serving / workers as separate services? (default: yes if AI/ML or long jobs exist)

Next.js app (App Router)

app/            # routes; server components by default
components/     # one component per file; ui/ for primitives
hooks/          # use*.ts
lib/            # pure utils, api clients, auth
services/       # domain logic calling APIs
public/         # assets: images/ fonts/ icons/ (industry conventions)
styles/         # globals.css, tokens

Turborepo monorepo (multiple frontends)

apps/           # app/ marketing/ studio/ admin/ … (one Next.js app each)
packages/       # ui/ auth/ config/ types/ eslint-config/
turbo.json  pnpm-workspace.yaml

FastAPI backend

app/
  api/v1/endpoints/   # thin route handlers
  services/           # business logic, LLM/external APIs
  core/               # config, db, redis, security — no business logic
  workers/            # celery tasks
  models/  schemas/   # SQLAlchemy | Pydantic
database/schema.sql   # single source of truth

Full platform (frontend + backend + ML + infra)

apps/{frontend…, backend-api, worker, model-serving}
packages/   docs/   infra/{docker, cloudflared}   scripts/   .github/workflows/
docker-compose.yml   .env.example   README.md

Naming conventions

One convention per language, applied everywhere — a mixed-case codebase is a review failure, not a style choice.

Rules

• URL pattern for APIs: /api/v1/{feature}/{action} (path versioning — the default, what Stripe/GitHub/most SaaS expose publicly). Bump to /v2 only on a breaking change; additive fields never bump. Alternative seen at scale (Stripe internally): a date-based version header instead of a path segment — only reach for it if you truly need per-customer version pinning; path versioning is simpler and is the default. Keep endpoints thin, logic in services.
• public/ mirrors industry conventions; docs live in docs/, never scattered.
• Shared code goes to packages//lib/ on second use — DRY is structural.
• Env: every var documented in .env.example; secrets never committed.
• New file? It has exactly one obvious home in the trees above. If it doesn't, the task is misdesigned — stop and fix the plan.