Handbook · architecture

The map that should remain in your head throughout the course.

Frameworks change details. Responsibility, trust, ownership, and evidence are the durable mental models.

Core request path

Figure H.1 — Create/update request

User + browser

Next.js UI/form

HTTP API client

NestJS auth/validation

Service/policy

Prisma

PostgreSQL

The response walks back through the same boundaries. Ask what each layer owns and what errors it may produce.

State ownership

URL state

Shareable/navigation state: filters, page, sort, selected view when appropriate.

Server state

Authoritative remote data: TanStack Query / server fetching, not duplicated into local state.

Form state

Temporary user editing intent: React Hook Form + validation feedback.

Local UI state

Ephemeral interaction: menu open, dialog tab, hover/preview.

Global client state

Use only for genuine cross-cutting client-owned values that do not fit the categories above.

Production topology

Figure H.2 — Production release path

Git commit SHA

CI verification

Immutable artifact

Vercel web + API host

Supabase services

DNS/TLS/CORS

Monitoring

Migrations, secrets, smoke tests, health checks, and rollback are part of the release system, not afterthoughts.

Architecture test: for any feature, explain where input is validated, identity is verified, permission is checked, business rules run, durable data changes, errors are mapped, and evidence is logged. If two layers both claim the same source of truth, investigate.