development-monorepo-pnpm-3darch/references/applications-backend.md

Backend Applications

Everything under applications-backend/*: NestJS service layout, configuration, ports and base paths, health checks, and the service container image.

Read this when adding a service, adding an endpoint to one, changing configuration or environment variables, assigning a port or base path, or debugging a service that will not start.

Default framework: NestJS. If the project architecture specifies otherwise, follow the architecture — the layout rules below that are framework-neutral still apply.

---

1. Service workspace layout

applications-backend/<service-name>/
├── src/
│   ├── main.ts                   # bootstrap — the only file that binds a port
│   ├── app.module.ts             # root module, imports feature modules
│   ├── config/
│   │   ├── configuration.ts      # typed config factory, reads process.env once
│   │   └── validation.ts         # schema; process exits if the env is invalid
│   ├── health/                   # liveness and readiness endpoints
│   └── <feature>/
│       ├── <feature>.module.ts
│       ├── <feature>.controller.ts    # HTTP surface only
│       ├── <feature>.service.ts       # business logic
│       ├── dto/                       # request/response shapes
│       └── entities/
├── test/
├── Dockerfile
├── nest-cli.json
├── package.json
├── tsconfig.json
└── tsconfig.build.json

One responsibility per layer, and the boundary is enforceable by review:

Layer	Holds	Never holds
*.controller.ts	routing, param binding, response shape	business rules, direct DB access
*.service.ts	business logic, orchestration	HTTP concerns, @Res(), status codes
dto/	validated request/response shapes	logic
entities/	persistence models	HTTP or transport concerns

A controller that reaches past its service into a repository is the most common drift in this layout, and it is invisible until you try to reuse the logic from a queue consumer or a cron job and discover it only exists inside an HTTP handler.

2. Configuration and environment

Read process.env in one place — the config factory — and inject typed config everywhere else. Scattered process.env reads make it impossible to know a service's full input surface, which is exactly what you need when writing the Helm values.

// src/config/configuration.ts
export default () => ({
  port: parseInt(process.env.PORT ?? "3000", 10),
  basePath: process.env.API_BASE_PATH ?? "/api/<service-name>",
  database: { url: process.env.DATABASE_URL },
});

Validate at startup and fail fast. A service that boots with a missing variable and fails on the first request that needs it turns a config error into a production incident, and the stack trace points at the wrong place.

Every variable added here must also be added to the Helm values and the service's documented env surface — see references/containers-and-helm.md.

3. Ports and base paths

Both are cross-cutting contracts, not local settings:

• The port appears in main.ts, the Dockerfile EXPOSE, the Helm values, and the service's Kubernetes Service definition.
• The base path appears in main.ts (app.setGlobalPrefix()), the gateway or ingress routing, and every frontend caller.

Assign a port from the repository's documented range and record it in the paired code-agent memory-bank/ — that record is what stops the next service from colliding with it. Changing either value is a blast-radius change (SKILL.md §8).

// src/main.ts
const app = await NestFactory.create(AppModule);
app.setGlobalPrefix(config.basePath);
app.enableCors({ origin: config.corsOrigins });
await app.listen(config.port);

4. Health checks

Expose two endpoints, and keep them different:

• Liveness — is the process alive? No dependency checks. A liveness probe that checks the database restarts a healthy service every time the database blips, turning a partial outage into a total one.
• Readiness — can it serve traffic now? Checks dependencies it genuinely needs.

5. Consuming shared packages

Backend services consume packages-backend/* with workspace:*. They must never import from packages-frontend/*.

A service that defines an API contract publishes it as packages-backend/<domain>-contracts, types only, so frontend applications can import it type-only — see SKILL.md §3. Adding a runtime dependency to a contract package breaks that guarantee for every frontend consumer.

6. Container image

Multi-stage build using turbo prune to produce a minimal snapshot of just this service and its workspace dependencies. Pruning is what stops an unrelated workspace change from invalidating this image's layers.

FROM node:22-alpine AS pruner
WORKDIR /app
RUN corepack enable
COPY . .
RUN pnpm dlx turbo prune --scope=@<scope>/<service> --docker

FROM node:22-alpine AS builder
WORKDIR /app
RUN corepack enable
COPY --from=pruner /app/out/json/ .
RUN pnpm install --frozen-lockfile
COPY --from=pruner /app/out/full/ .
RUN pnpm turbo run build --filter=@<scope>/<service>

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -S app && adduser -S app -G app
COPY --from=builder --chown=app:app /app .
USER app
EXPOSE <port>
CMD ["node", "applications-backend/<service>/dist/main.js"]

Points that matter:

• out/json/ is copied and installed before out/full/ so dependency installation caches independently of source changes.
• --frozen-lockfile makes the build fail rather than silently resolve different versions.
• Run as a non-root user. The default is root, and nothing warns you.

7. Validation

pnpm check-types --filter="@<scope>/<service>"
pnpm lint        --filter="@<scope>/<service>"
pnpm build       --filter="@<scope>/<service>"
pnpm dev         --filter="@<scope>/<service>"    # it must actually boot

curl -s localhost:<port>/<basePath>/health | jq .

A build that passes proves the types line up; only starting the service proves the config validation and port binding do.

8. Mistakes to avoid

• Reading process.env outside the config factory.
• Booting successfully with invalid configuration instead of failing fast.
• A liveness probe that checks dependencies.
• Business logic in a controller.
• Importing from packages-frontend/*.
• Giving a contract package a runtime dependency.
• Changing a port or base path without updating Helm values, gateway routing, and callers.
• Hardcoding a base path string in a frontend caller instead of deriving it from the contract.
• Running the container as root.