Every business domain is organized into six layers with strict forward-only dependencies.
Types → Config → Repo → Service → Runtime → UI
│ │ ▲
└── Zod request/response schemas ─────┘ │
│ │
▼ │
OpenAPI spec + typed API client
+ TanStack Query helpers ───────────┘
| Layer | Purpose | May Import |
|---|---|---|
| types/ | Domain types, Zod schemas, constants | Nothing (leaf layer) |
| config/ | Domain configuration, defaults, env parsing | types |
| repo/ | Data access, database queries, external API clients | types, config |
| service/ | Business logic, orchestration, domain rules | types, config, repo |
| runtime/ | Server routes, route contracts, background jobs, event handlers | types, config, repo, service |
| ui/ | React components, hooks, pages; uses generated API client and TanStack Query helpers for HTTP | types, config (client-safe only), generated client |
Route contracts live in runtime/contract.ts because they describe the HTTP boundary. They depend on lower-layer Zod schemas and provider contract types, then feed generated artifacts under src/generated/. UI code may import the generated client, generated TanStack Query option factories, generated query keys, and exported client-safe types, but it must not import runtime route modules directly.
Database, telemetry, auth, feature flags, and shared connectors (cache, queue) live in src/providers/. Any layer may import from providers — this is the only exception to the forward-only rule.
src/providers/
├── database/ # Postgres client and lifecycle
├── openapi/ # Route contract to OpenAPI document builder
├── telemetry/ # Structured Pino logging; metrics/traces are future work
├── auth/ # Authentication & authorization
└── feature-flags/ # Feature flag evaluation
These rules are enforced by the custom linter at lints/check-deps.ts:
- No backward imports.
types/cannot import fromservice/.repo/cannot import fromruntime/. Period. - No cross-domain imports at lower layers.
domainA/repocannot importdomainB/repo. Cross-domain communication happens at theservicelayer or above. - No direct cross-cutting imports. Use
src/providers/, not rawpinoor@opentelemetry/*imports in domain code. - UI only imports types and client-safe config. No server-side code in the UI layer.
- Generated API client is the UI HTTP boundary. Browser code should use
src/generated/api-client.generated.ts, preferably through generated TanStack Query helpers, not hand-writtenfetchwrappers for app routes. - Co-located tests are required. Source modules must have adjacent unit or integration tests unless they are approved entrypoints, generated files, or barrel files.
- Structured logging only. Application code must not use
console.*; use providers so stack logs stay queryable.
- Create
src/domains/<name>/with all six layer directories - Add types and Zod schemas first (types layer is the foundation)
- Add route contracts and route handlers in the runtime layer
- Register domain contracts in
src/api-contracts.ts - Run
pnpm api:generatewhen HTTP behavior changes - Add co-located tests for every source module
- Add browser e2e coverage when the domain exposes user-visible flows
- Update implementation.md, testing.md, openapi.md, or domain-specific docs when behavior changes
- One export per file preferred (agents navigate better)
- Co-locate tests:
foo.ts→foo.test.ts; database tests usefoo.integration.test.ts - Max file size: 300 lines (enforced by linter)
- Schemas named
<Thing>Schema, types inferred astype Thing = z.infer<typeof ThingSchema>