AGENTS.md — NestJS service

A modular TypeScript service where each domain is a Nest module with its own controllers, providers and tests, wired by dependency injection.

Setup and commands

• dev: npm run start:dev
• e2e: npm run test:e2e
• lint: npm run lint && npx tsc --noEmit
• test: npm test
• build: npm run build
• install: npm ci

Project structure

• src/main.ts — Bootstrap: global pipes, filters, security headers, shutdown hooks
• src/app.module.ts — Root module importing config, database and feature modules
• src/modules/<domain>/ — One folder per domain: module, controller, service, dto/, entities, *.spec.ts
• src/common/ — Guards, interceptors, exception filters and decorators shared across modules
• src/config/ — Typed configuration validated at startup
• prisma/ — schema.prisma and migrations
• test/ — End-to-end specs that boot the app with Supertest

Code style

• Files: kebab-case.<role>.ts, e.g. orders.controller.ts
• Tests: *.spec.ts beside the unit; test/<domain>.e2e-spec.ts
• Branches: type/short-description, e.g. fix/billing-proration

Code

• Prefer small, pure functions and explicit types at module boundaries. (Easier to test, review and change.)
• A module exports only the providers other modules need; cross-module calls go through those exported services, never through another module’s repository. (Keeps domain boundaries real so a module can be extracted later.)
• Controllers translate HTTP to service calls and nothing more; no Prisma calls in controllers. (Business rules stay testable without HTTP.)

Components

• Components read design tokens; no raw hex values, pixel sizes or font names in component code. (One token change restyles the product.)

Data

• Analytics events are object_action in snake_case and come from the experience skill’s measures. (Names stay consistent across teams and tools.)
• Enable a global ValidationPipe with whitelist, forbidNonWhitelisted and transform; every body and query is a DTO class. (Unknown fields are rejected before they reach a service.)

Errors

• Every async action has loading, empty, error and success states, matching the experience skill. (Unhandled states are where users get stuck.)
• Map domain errors to HTTP in one exception filter; services throw domain errors, not HttpException. (Services stay transport-agnostic and errors stay consistent.)

Security

• Secrets never live in the repository; read them from the environment or a secret store. (A leaked key outlives the commit that removed it.)
• Validate every input on the server, even when the client already did. (Clients can be bypassed.)
• Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. (Cheap protection against the most common attacks.)
• Protect routes with guards that are on by default (global auth guard) and opt out explicitly with a @Public() decorator. (Forgetting a decorator fails closed instead of open.)

Performance

• Move anything slower than 200ms or dependent on a third party into a queue job with retries and idempotency keys. (Keeps request latency predictable when dependencies misbehave.)

Accessibility

• Use native elements first; add ARIA only when no native element fits. (Native controls bring keyboard and screen-reader support for free.)

Design and journeys

This stack has no UI; design skills do not apply.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events object_action from its measures.

Testing and checks (must pass before a pull request)

Pull requests

• Branching: Trunk-based: short-lived branches off main, squash-merged within two days.

Review checklist

• Correctness: does it do what the issue asks, including edge cases?
• Readability: could a new teammate change it safely?
• Architecture: is it in the right place, with the right boundaries?
• Security: inputs, secrets, permissions, dependencies
• Performance: budgets, queries, bundle size
• Tests fail when the code is broken (flip a condition and re-run)
• Module owners review changes inside their module
• Two reviewers for auth guards, migrations or anything touching money

Definition of done

• Acceptance criteria met and demoed on the preview link
• Tests added for new behaviour and every state
• Accessibility and performance gates green
• Analytics events named from the experience skill
• Docs or changelog updated when behaviour changes
• DTOs validate every input field
• Unit spec for the service and an e2e spec for the route

Release

• Small pull requests (aim for under 400 changed lines)
• CI green before review
• Squash-merge to main; main is always deployable
• Every release has a written rollback path
• Merge to main deploys API and worker images together with a rolling update
• Prisma migrations are backwards compatible with the previous release

Incidents

• Roll back by redeploying the previous image; pause queues if jobs are failing
• Blameless note within 48 hours

Generated from the Celestial engineering skill “NestJS service” (engineering core v1.0, checked 2026-10-26).