layered-architecture

name

layered-architecture

description

Enforce the layered architecture in this TanStack Start app — routes/components/hooks/queries call server functions in `src/fn/`, which call use cases or data access; only `src/data-access/` touches Drizzle/the database. Use when adding or modifying any feature that crosses the client→server→DB boundary, creating files in `src/routes/`, `src/components/`, `src/hooks/`, `src/queries/`, `src/fn/`, `src/use-cases/`, or `src/data-access/`, or when reviewing where a new function belongs. Trigger phrases: "add a feature", "create endpoint", "new server function", "fetch data", "save to database", "where does this go".

Layered Architecture (this repo)

The dependency chain is fixed. Each layer imports only from layers below it.

routes  →  components  →  hooks  →  queries  →  fn  →  (use-cases)  →  data-access  →  db

Third-party infra I/O (Stripe API calls, S3/R2 presigning, email send) is data-access-shaped — wrap each provider in a module under src/data-access/ (e.g. data-access/stripe.ts) and call it from fn or a use case. Do not call SDKs directly from fn/ or use-cases/.

use-cases is optional — only insert it when business rules span multiple data-access calls or enforce policy (plan limits, ownership across entities, multi-step invariants). Plain CRUD goes fn → data-access directly.

Where each concern lives

Quick lookup — full layer purposes are in docs/architecture.md. Do NOT re-read that doc unless this table is ambiguous for your case.

Concern	Layer
URL params, route loaders calling queryClient.ensureQueryData