backend-architecture

The folder skeleton of a feature and the order to build it in — which artifact comes first, which skill owns each step, and the checklist that catches what gets forgotten. This skill is the index; every step's pattern lives in the skill it names. Trigger on — adding a feature or module, adding an endpoint or a resource, building CRUD for something new, scaffolding a feature from scratch, wiring a feature into the application, asking where a file goes, or asking what is left to finish a feature.

The generated OpenAPI document — `@Api*` decorators on DTOs and controllers, declaring both security schemes, tag groups, operation ids, documenting a restriction a guard enforces, and controlling who can reach the docs endpoint. Trigger on — adding `@ApiProperty`, `@ApiPropertyOptional`, `@ApiOperation`, `@ApiResponse`, `@ApiTags`, `@ApiBearerAuth` or `@ApiCookieAuth`, editing the docs setup, adding a controller to the document, a field missing from the generated schema, an endpoint appearing without a tag or in no group, a generated client with colliding method names, or exposing the documentation endpoint in an environment.

The application layer of a feature — use cases, command objects, result objects, domain policies that return a verdict, infrastructure port interfaces and their environment-switched adapters, the actor that performed the action, batch orchestration with per-item results, and the rules for depending on another feature. Trigger on — writing or editing a `*.usecase.ts`, `*.command.ts` or `*.policy.ts`, deciding whether code should throw or return a value, deciding what a use case returns, injecting another feature's repository or use case, adding a port for email/SMS/storage/payments, swapping a real provider for a simulator outside production, setting who performed an action, writing an endpoint that processes many rows and must report each one, a use case that grew a second responsibility, or two features that each need the other, or an id stored without checking that it resolves.

The audit trail — the `AuditLog` entry, the `Actor` value object and its project-defined type catalog, recording who changed what and why, the `changes` before/after convention, keeping entries in their own collection rather than inside the entity's document, writing the trail alongside the aggregate, enriching entries with request metadata in infrastructure, and reconciling an append-only trail with an erasure request. Trigger on — adding audit tracking to an entity, calling `AuditLog.create(...)` or appending to an entity's entries, using `Actor` or `performedBy`, recording a change made by a scheduler or an event handler, writing the audit repository, deciding what belongs in the description versus the metadata, a state change with no record of who made it, or a data-deletion request against records that must be kept, or an audit entry written for an update that changed nothing.

Proving who a caller is — password hashing behind a port, issuing access and refresh tokens, what belongs in the token versus what is looked up, carrying the token in an HttpOnly cookie by default with a bearer header as the alternative for non-browser clients, the guard's resolution order, mirroring the transport in the login and refresh responses, refresh rotation and reuse detection, logout and revocation, the authentication guard and the principal it attaches, and marking a route public. Trigger on — writing login/refresh/logout, hashing or verifying a password, signing or verifying a token, choosing token claims or lifetimes, setting or clearing an auth cookie, writing the authentication guard or `@CurrentUser()`, a mobile or service client that cannot use cookies, a session that cannot be revoked, or a stolen refresh token, a session that survives a password change, or two simultaneous refreshes that both succeed, a logout that answers 401, or a session that survives signing out.

Deciding what a caller may do — the permission catalog as the single source, roles as named sets of permissions, the permission guard and its decorator, a superuser bypass, the staleness cost of carrying permissions in the token, and resource-level access: ownership, tenant scoping, and answering not-found instead of forbidden. Trigger on — adding or using a permission, writing `@RequirePermissions` or the permission guard, adding a role or changing what a role grants, a caller who passes the route guard but is reading somebody else's record, scoping a query to a tenant, choosing between 403 and 404 for a record the caller may not see, a permission change that does not take effect until the user signs in again, or an endpoint that only checks the verb and not the row, or a route reaching a handler without declaring any permission, a caller type invented to grant more access, or a listing that returns records the by-id endpoint refuses.

Work that runs without a request — scheduled jobs and why a schedule needs a lock once there is more than one replica, taking and releasing that lock safely, overlapping runs, jobs as thin callers of use cases, retries with backoff and a dead-letter destination, making a job resumable and idempotent, batching over large collections, and the reconciliation sweep that finishes work an event handler missed. Trigger on — adding a scheduled or cron job, a job that ran twice or produced duplicate records after scaling out, a job still running when the next run starts, a long job that fails halfway and cannot be re-run, retrying failed work, moving repeatedly failing work aside, or sweeping records left in an intermediate state.

Universal TypeScript/NestJS conventions for every file in any layer — forbidden constructs (`any`, non-null `!`, `console.*`, `as` outside sanctioned cases), explicit type annotations, `interface` for contracts vs `type` for data, absence via `undefined` not sentinels, no magic values, constructor injection only, pure functions, no mutation of data you don't own, type-only imports, floating promises, named exports, comments and JSDoc policy, blank lines, brace style, and the naming table. Trigger on — writing or editing ANY `.ts` file, declaring a class/type/interface, injecting a dependency, casting with `as`, inlining a literal, binding a value to a `const`, mutating an array or object, calling an async function, naming a file/class/constant/token/route, declaring a value union, deciding `?` vs `| undefined`, adding a comment or JSDoc, choosing an export style, a lint rule that contradicts a documented convention, or reviewing code for convention compliance.

Environment variables and operator-editable settings — the validated `EnvironmentVariables` class, why every variable is required with no default and no fallback in the reader, coercing numeric and boolean values, the typed `ConfigService`, keeping `.env.example` as the contract, the test for whether a value belongs in the environment or in the database, and the settings aggregate for values an operator changes. Trigger on — adding or reading an environment variable, editing the env validation class, updating `.env` or `.env.example`, injecting `ConfigService`, a numeric or boolean variable arriving as a string, deciding whether a price/fee/limit/quota belongs in the environment, branching on `NODE_ENV`, an application that started with a missing variable and failed later, or moving a value out of the environment into the database, or a seed that creates what is missing but never updates what is already there, a variable that is declared but empty, or two settings that are each valid and wrong together.

The domain layer of a feature — entities, aggregate roots, value objects, enum-like value unions, domain events, domain error classes, repository interfaces, the opaque `Transaction` type, decimal and money scale, and the `?` vs `null` convention across layers. Trigger on — writing or editing a `*.entity.ts`, a value object, a `*.events.ts` or `*.errors.ts` file, a repository interface (`I*Repository`), extending `AggregateRoot`, writing `create()` or `reconstitute()`, deciding whether a rule is a getter or a policy, deciding whether a value object belongs in the feature or in `common/`, storing a monetary or decimal amount, adding a second enum-like axis to an entity, choosing where an exported constant lives, a PATCH field that must distinguish 'unchanged' from 'cleared', or a state change that updated the row but emitted no event, or a field that cannot be cleared once it has been set.

Turning failures into responses — the domain error to HTTP status map, the global exception filter, the shape of a validation failure, why an unmapped domain error is a 500, classifying a refusal against a fault, the two valid endings for a `catch`, and the empty-body pitfall on an all-optional DTO. Trigger on — editing the errors map or the global exception filter, choosing an HTTP status for a new domain error, writing a `catch` block, a `catch` that only logs, an error reaching the client as 500 when it should be 4xx, a validation failure whose response shape differs from other errors, an empty request body that produces a 500 instead of a clean rejection, or deciding whether a failure is the caller's fault or the system's, a 403 answered to a request carrying no credentials, or a 409 that is really a bad value, or a 400 whose message list is empty.

Publishing and handling domain events — the event bus interface, draining an aggregate's event buffer, publishing after the commit and never inside the transaction, registering handlers, what a handler may and may not do, why handlers never throw, the in-process bus versus a durable outbox and when the difference starts to matter, and evolving an event's shape. Trigger on — writing an `@OnEvent` handler or a `*.handlers.ts` file, calling `getEvents()` or `_eventBus.publish(...)`, wiring a side effect that changes another aggregate, an event that fires but whose effect never happens, events lost after a retry, an event that fires twice, a handler that throws and takes the request down with it, adding a field to an existing event, or a feature that needs to react to another without depending on it, or a deleted record whose id stays behind in another feature.

Talking to systems you do not control — the provider adapter behind a port, timeouts, retrying only what is safe to retry, sending an idempotency key outward, circuit breaking, validating a response instead of trusting its type, never calling out inside a transaction, receiving webhooks with signature verification and replay protection, and simulators that stand in for a provider outside production. Trigger on — writing an adapter or a client for a third-party API, a request with no timeout, a retry that charged a customer twice, a slow dependency taking the whole service down with it, parsing a provider response, receiving a webhook, verifying a signature, a webhook delivered twice or out of order, or replacing a provider with a simulator.

The branching and commit methodology — the long-lived branches and which direction changes flow between them, feature and fix branch naming, Conventional Commits with a feature scope, what belongs in one commit, and keeping documentation and skills in the same commit as the change they describe. Trigger on — creating a branch, naming a branch, writing a commit message, choosing a commit type or scope, splitting work across commits, deciding which branch to start from or merge into, or a change to a pattern that leaves its skill unedited.

Translated text leaving the backend — the translation file layout per feature namespace, the success message in the response envelope, resolving the language of a request, resolving the language of a notification from the recipient rather than the sender, wiring validator messages, domain error codes as translation keys, and keeping every key present in every configured locale. Trigger on — adding or editing a translation file, setting a response message, adding a locale, wiring `i18nValidationMessage` on a validator, translating a domain error, an error that renders its key instead of a sentence, an email or notification that arrived in the wrong language, adding a new feature's translation namespace, or adding a member to a value union that has user-visible labels.

NestJS module composition — the feature module's shape, DI tokens as `unique symbol`, binding an interface to an implementation, what a module may export, the policy for `@Global()` modules, selecting an implementation per environment with `useFactory`, provider scope and why request-scoped is contagious, lifecycle hooks, and breaking a dependency cycle between features. Trigger on — writing or editing a `*.module.ts`, registering a provider or a token, exporting something from a module, importing another feature's module, choosing between `useClass`/`useFactory`/`useValue`, a `Nest can't resolve dependencies` error, a circular import that only fails at boot, reaching for `forwardRef`, deciding whether something belongs in a global module, or code that must run at startup or shutdown, a simulator that is never selected, or a stub that answers plausibly in production.

Knowing what the running process is doing — the framework `Logger` instead of `console.*`, structured log lines on stdout, the level policy and what makes a level worth alerting on, the trace id generated at the edge and carried through every line and response, the ambient request context, correlating work that outlives the request, masking sensitive fields, health checks, and graceful shutdown. Trigger on — adding a log line, reaching for `console.log`/`console.error`, choosing a log level, a log that prints an object as `[object Object]`, a trace id that is missing or different between two lines of one request, reading the current request deep in the call stack, a scheduled job or event handler whose logs cannot be tied to anything, adding a health endpoint, a deploy that drops in-flight requests, a password or token appearing in output, a masked value that still shows part of itself, an error that logs as an empty object, or not knowing which host or database the process connected to.

Paged list endpoints — the shared `ListQuery` and `ListQueryDTO`, the `Paginated<T>` result and its metadata, paging in the database rather than in memory, optional filters, the sortable-field whitelist and the stable tiebreaker, the cost of a total count, offset versus cursor paging, and denormalizing a field so a filter or aggregation can use an index. Trigger on — adding a list endpoint, adding a filter or a sort option to a query, extending `ListQuery` or `ListQueryDTO`, building a `Paginated<T>`, a page whose items repeat or vanish when you page through it, a list endpoint that gets slower the deeper you page, a filter that scans the whole collection, or an aggregation over a field stored inside a related document, or a filter the API documents and the query ignores.

The persistence side of a feature's infrastructure — Mongoose schemas, index declaration and compound-index ordering, partial unique indexes, persistence mappers (`toDomain`/`toPersistence`), repository implementations, narrowing the opaque `Transaction` to a driver session, soft delete, filter building, projections and `lean()`, avoiding N+1 reads, and schema migrations. Trigger on — writing or editing a `*.schema.ts`, a `*-mongo.repository.ts` or a `*.persistence-mapper.ts`, declaring an index, adding a field to a stored document, implementing `save()` or `getById()`, a query that ignores deleted records, a unique constraint that must allow repeated nulls, a slow query or a collection scan, a loop that queries once per element, or backfilling existing documents after a schema change, or a duplicate-key violation reaching the client as a 500, or an index definition that was edited and left its predecessor behind.

The HTTP surface of a feature — controllers, request/query/response DTOs and their validators, presentation mappers, the `APIResponse` envelope and its builder, status codes per verb, guard composition and ordering on a route, extracting the authenticated principal into an actor, optional relation loading via `?include=`, batch route shape, and gating a route to non-production. Trigger on — writing or editing a `*.controller.ts`, a `*.dto.ts` or a `*.presentation-mapper.ts`, choosing a status code or route name, building a response, stacking guards on a route or controller, turning the current user into the command's actor, adding an `?include=` parameter, exposing an endpoint only outside production, an endpoint leaking an entity or a persistence field, or a response whose shape differs between two endpoints.

Standing a new backend up and the files every project needs before any feature exists — the source tree and what `common/` holds, the `@/` path alias, compiler strictness, lint and format setup, package scripts, the pre-commit hook, `main.ts` and the order its steps must run in, global pipes and filters, the root module, and the local development stack. Trigger on — starting a new project or repository, configuring which lint rules are enabled, editing `main.ts`, `app.module.ts`, `tsconfig.json`, the lint config or `package.json` scripts, adding a global pipe/filter/guard, deciding where a cross-cutting file goes, an import that resolves in the editor but not at runtime, a setting that must be applied before the application listens, or setting up the local database, a build that emits `dist/src/main.js` instead of `dist/main.js`, or a container that cannot bind its port because another project holds it.

Hardening the request surface — stripping and rejecting undeclared body fields, body size limits, escaping user input before it reaches a regular expression, file upload validation by content rather than extension, rate limiting per principal and across replicas, CSRF defense for cookie-authenticated requests, CORS with credentials, response headers, handling secrets, and classifying personal data. Trigger on — configuring the validation pipe, a field that reached the database without being declared on the DTO, building a search filter from user text, accepting a file upload, adding a rate limit, a limiter that does not hold across replicas, enabling CORS or configuring allowed origins, defending against a forged cross-site request, adding a secret, or deciding whether a field is personal data, or a secret compared with ===, or a cookie setting that quietly disables SameSite.

What to test and how — the unit, integration and end-to-end boundaries and their file suffixes, arrange/act/assert, what each layer is worth testing for, doubling a port with a plain typed object instead of a test module, doubling the transaction manager, builders for entities with private constructors, injecting the clock and the id generator so results are deterministic, and what not to test. Trigger on — writing or editing a `*.spec.ts`, `*.integration-spec.ts` or `*.e2e-spec.ts`, deciding what to cover for a new use case or entity, stubbing a repository or a port, constructing an entity in a test, a test that fails intermittently, a test that breaks whenever an unrelated field is added, a test that needs a database, or asking what a change still needs covered, a test suite that arranges its own pipes and middleware, or a test that stays green while the bug it covers is live.

Units of work and what they do and do not guarantee — the transaction manager, why a transaction is not a lock, write conflicts and why retries make the callback re-runnable, what must be hoisted above `run(...)`, the one-aggregate atomicity boundary, unique indexes as the only real uniqueness guarantee, serializing a rule with a guard document, idempotency keys and request fingerprints, at-least-once delivery, eventual consistency, compensations and reconciliation. Trigger on — wrapping work in `_transactionManager.run(...)`, a quota/balance/uniqueness check that passes in manual testing and fails under two simultaneous requests, a duplicate record created by a double click or a retried request, a transaction that commits partially, work that must span two aggregates, an external call inside a transaction, designing a retry or reconciliation job, a state change that must happen once happening twice, or an idempotency key reused with a different body.