The NestJS scaffold

The backend was generated with the official Nest CLI (nest new) and then tuned for a strict test gate. This page explains the moving parts so you can extend it confidently.

What nest new gives you

• A module graph rooted at AppModule (src/app.module.ts) that declares the app's controllers and providers.
• An example controller (app.controller.ts, serving GET /) and provider (app.service.ts), plus the bootstrap entrypoint (main.ts).
• A unit spec (app.controller.spec.ts) and an end-to-end spec (test/app.e2e-spec.ts).
• Tooling: nest-cli.json, tsconfig*.json, an ESLint flat config, and Prettier.

How NestJS fits together

NestJS is a structured, dependency-injection framework:

• Modules group a feature's controllers and providers and declare what they import and export. AppModule is the composition root; each feature gets its own module.
• Controllers handle HTTP — routes, params, status codes. Keep them thin.
• Providers / services hold the business logic and are injected through the constructor; Nest resolves them from the DI container.
• main.ts boots the app with NestFactory.create(AppModule) and listens.

How we tuned it, and why

• Full TypeScript strict for real type safety (checked by npm run typecheck).
• Jest transformed by SWC (.swcrc) instead of ts-jest. ts-jest's emitDecoratorMetadata emits an untestable phantom branch on every decorated DI constructor, which capped branch coverage around 75% and made an honest 90% branch gate impossible. SWC's metadata emit avoids that artifact, so coverage is a true 100% on the scaffold (and tests run faster). Because SWC doesn't type-check, tsc does that in a separate typecheck step.
• A module smoke test (app.module.spec.ts) compiles the DI graph, keeping modules inside the coverage gate (unit specs alone only touch the controller and service in isolation).
• main.ts is excluded from coverage (it's the bootstrap), and void bootstrap() keeps the lint clean.

Adding a feature

Use the CLI so the files are wired into the module graph and consistent:

npx nest generate resource <name>   # module + controller + service + DTOs + specs
# or finer-grained: nest g module|controller|service <name>

Then write the tests first (happy path + errors + edges), implement until npm run verify is green, add an e2e test in test/, and update the four sources of truth plus this wiki. The full loop is in docs/WORKFLOWS.md.