All guides
Architecture
The directory layout, the layering rules and the boundary between the domain and the framework.
Updated 2026-10-21
Layers
Each layer can only depend on the layer below it.
- src/types: the data model and the API contract. No logic.
- src/lib: domain services, validation, storage and provider clients.
- src/services: use cases that orchestrate the domain services.
- src/app: route handlers and pages. They translate a request into a service call.
- src/components: the user interface. It never talks to a provider directly.
Rules
The rules that keep the codebase maintainable.
- A route handler validates its input, resolves the session, calls one service and maps the result to a response envelope.
- A service never imports from src/app or src/components.
- A provider client is server only and is always reached through an injected dependency so it can be replaced in a test.
- Every response uses the shared envelope so the client never parses two shapes.