Module Structure

Backend Module Structure

NestJS organizes code into feature modules. Each owns a controller (REST routes), service (data access + business logic), and a *.schemas.ts file (zod schemas + DTO classes via nestjs-zod's createZodDto).

src/
  app.module.ts    # Root - imports every feature module
  main.ts          # Bootstrap: secret validation, CORS, /openapi.json, /docs (dev)
  db/              # Row interfaces (types.ts) + integration-spec gating.
                   #   Migrations live in ../migrations/
  knex/            # KNEX_CONNECTION provider, global
  common/          # pagination (parseOffset, clampLimit, max 200),
                   #   body-parsers (raw for Stripe), worker-claim, common.schemas
  auth/            # AuthService.validateSession, SessionGuard,
                   #   InternalApiTokenGuard, @CurrentUser(),
                   #   session-cleanup.worker (hourly TTL + audit-table sweep)
  internal/        # The NextAuth adapter endpoints, X-Internal-Token only
  rate-limit/      # DB-backed magic-link limiter + its internal endpoint
  users/           # Account deletion: ghostDelete, queue, user-deletion.worker
  items/           # Example CRUD module - copy this shape
  blog/            # Public read controller + admin CRUD controller
  admin/           # AdminGuard + /admin/users (list, grant/revoke admin)
  email/           # send / queue / queueBulk, @Cron processor, admin stats
  billing/         # Stripe, optional-by-config. billing-subscription-store.ts
                   #   is the ONLY writer of billing state (disputed lock,
                   #   event cursor). stripe-webhook.controller takes a raw
                   #   body and is excluded from OpenAPI. See docs/Billing/
  mcp-admin/       # AI-agent admin surface: POST /admin/mcp, tool registration
  mcp-shared/      # Reusable stateless transport, OAuth 2.1 factory, rate
                   #   limits, safeTool. See docs/Admin MCP Server.md
  scripts/seed.ts  # Database seed

Frontend Structure

frontend/
  auth.ts         # NextAuth: BackendAdapter, providers, session callback,
                  #   strategy 'database', production env assertions
  auth.config.ts  # Edge-safe slice (OAuth providers + pages) for the proxy
  proxy.ts        # /backoffice/* admin gate, /pricing + /blog/<slug> 404
                  #   gates (honest wire status when notFound() lands in a
                  #   streamed response), per-request CSP nonce
  app/            # App Router: marketing, blog (ISR), signin, settings,
                  #   pricing, billing, backoffice, api/auth route handler
  lib/            # api.ts (the three clients + DTO re-exports),
                  #   auth-adapter.ts (14 methods over internalApi()),
                  #   public-session.ts (the session allowlist),
                  #   RSC data helpers, markdown, safe-callback-url
  types/api.d.ts  # Generated by `npm run generate-types`

DTO Extractor Pattern

Every module follows the same shape: a single *.schemas.ts file holds zod schemas, the createZodDto-wrapped DTO classes, and an extract*FromRow helper at the bottom. Services return raw rows; controllers call the extractor before returning. Walkthrough: Adding a Module.