spoonfeeder 0.1.0

package/templates/base/docs/adr/021-observability-strategy.md

@@ -0,0 +1,68 @@
+# ADR-021: Observability Strategy with OpenTelemetry
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+Production services require observability across three pillars: logs, traces, and metrics. Without a standardized approach, teams implement ad-hoc solutions that are inconsistent across services and difficult to correlate during incident response.
+
+## Decision
+
+Adopt OpenTelemetry (OTel) as the observability standard with the following components:
+
+### Tracing
+
+- `@opentelemetry/sdk-node` with auto-instrumentation for HTTP, database, and cache clients
+- W3C Trace Context (`traceparent` header) for distributed trace propagation
+- Trace IDs injected into Pino log lines via `nestjs-pino` for log-trace correlation
+
+### Metrics
+
+- `@opentelemetry/sdk-metrics` exporting to Prometheus via `/metrics` endpoint
+- Default metrics: request duration histograms, error rate counters, active connection gauges
+- Database connection pool metrics (pool size, idle, waiting) via custom instrumentation
+- `@nestjs/terminus` health checks: liveness (`/health/live`), readiness (`/health/ready`), startup (`/health/startup`)
+
+### Error Tracking
+
+- Sentry (`@sentry/nestjs`) for error aggregation, release tracking, and performance monitoring
+- Available as the `sentry` recipe — not baked into the base template
+- Source maps uploaded to Sentry during CI/CD build stage
+
+### Request Logging
+
+- Request/response logging middleware via `nestjs-pino` with correlation ID propagation
+- Configurable log sampling for high-traffic endpoints
+
+## Consequences
+
+### Positive
+
+- OpenTelemetry is vendor-neutral — exporters can target Jaeger, Datadog, New Relic, or cloud-native backends
+- W3C Trace Context ensures trace propagation works across any OTel-instrumented service
+- Health check probes integrate with Kubernetes liveness/readiness/startup probe configuration
+- Connection pool monitoring catches resource exhaustion before it causes outages
+
+### Negative
+
+- OpenTelemetry SDK adds startup overhead and memory for span collection
+- Auto-instrumentation can generate high trace volume — requires sampling configuration
+- Prometheus `/metrics` endpoint must be secured in production (not exposed publicly)
+
+### Risks
+
+- OpenTelemetry Node.js SDK maturity — some instrumentations are still in beta; mitigated by pinning to stable releases
+
+## References
+
+- [OpenTelemetry JS](https://opentelemetry.io/docs/languages/js/)
+- [W3C Trace Context](https://www.w3.org/TR/trace-context/)
+- Packages: `@opentelemetry/sdk-node`, `@opentelemetry/sdk-metrics`, `@nestjs/terminus`, `@sentry/nestjs`
+- Recipes: `sentry`, `datadog`, `prometheus`
+- ADR-017: Logging Strategy

package/templates/base/docs/adr/022-api-design-patterns.md

@@ -0,0 +1,64 @@
+# ADR-022: API Design Patterns as Opt-In Recipes
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+Production APIs need patterns like pagination, filtering, caching, and idempotency. However, not every API needs every pattern. Baking all patterns into the base template would add complexity and dependencies that many projects never use.
+
+## Decision
+
+Provide API design patterns as individual opt-in recipes, each implementing a well-defined RFC or industry standard:
+
+| Recipe           | Standard                | Description                                                                    |
+| ---------------- | ----------------------- | ------------------------------------------------------------------------------ |
+| `pagination`     | RFC 8288 (Web Linking)  | Cursor and offset pagination with `Link` header navigation                     |
+| `filtering`      | Custom (JSON query DSL) | Type-safe query filtering with `class-validator` DTOs                          |
+| `api-versioning` | URI + Header            | URI prefix (`/v1/`) and `Accept-Version` header strategies                     |
+| `correlation-id` | Custom                  | `x-correlation-id` header propagation via `AsyncLocalStorage`                  |
+| `idempotency`    | Idempotency-Key header  | Request deduplication with configurable storage (Redis/database)               |
+| `http-caching`   | RFC 9111                | `Cache-Control`, `ETag`, and conditional request support                       |
+| `prefer-header`  | RFC 7240                | `Prefer: return=minimal`, `respond-async` handling                             |
+| `json-patch`     | RFC 6902                | JSON Patch operations for partial resource updates                             |
+| `sse`            | EventSource API         | Server-Sent Events for real-time unidirectional streaming                      |
+| `webhooks`       | Custom                  | Webhook dispatch with retry, signing (`content-digest`), and delivery tracking |
+
+Each recipe provides:
+
+- A NestJS module or decorator that can be imported per-controller
+- DTOs with `class-validator` decorators for input validation
+- Integration tests demonstrating correct behavior
+- CLAUDE.md documentation for AI-assisted development
+
+## Consequences
+
+### Positive
+
+- APIs adopt only the patterns they need — no unused middleware or decorators
+- Each pattern follows an established RFC, ensuring interoperability
+- Recipes include tests and documentation, reducing implementation errors
+- Patterns are composable — `pagination` + `filtering` + `http-caching` work together
+
+### Negative
+
+- Developers must know which recipes to select — requires familiarity with API design patterns
+- Some recipes depend on others (e.g., `webhooks` benefits from `correlation-id`)
+- Recipe-per-pattern granularity means more items in the CLI selection prompt
+
+### Risks
+
+- RFC compliance drift as recipes evolve — mitigated by linking to the relevant RFC in each recipe's README and validating compliance in integration tests
+
+## References
+
+- [RFC 8288 — Web Linking](https://www.rfc-editor.org/rfc/rfc8288)
+- [RFC 9111 — HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111)
+- [RFC 7240 — Prefer Header](https://www.rfc-editor.org/rfc/rfc7240)
+- [RFC 6902 — JSON Patch](https://www.rfc-editor.org/rfc/rfc6902)
+- ADR-008: Composable Recipe System

package/templates/base/docs/adr/023-error-hierarchy.md

@@ -0,0 +1,54 @@
+# ADR-023: Typed Error Class Hierarchy
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-01
+
+## Context
+
+NestJS provides `HttpException` and its subclasses (`NotFoundException`, `BadRequestException`, etc.) for throwing HTTP errors. However, these are HTTP-layer concerns — using them in domain services couples business logic to the HTTP transport. Services that throw `HttpException` cannot be reused in message consumers, CLI commands, or gRPC handlers without dragging in HTTP semantics.
+
+## Decision
+
+Implement a typed error hierarchy rooted at `ApplicationError`:
+
+- **`ApplicationError`** — abstract base with `message`, `traceCode`, and optional `debugInformation`
+- **`ValidationError`** — input validation failures (maps to 400)
+- **`NotFoundError`** — requested resource does not exist (maps to 404)
+- **`ForbiddenError`** — authenticated user lacks permission (maps to 403)
+- **`InvalidRequestError`** — structurally valid but semantically invalid request (maps to 422)
+- **`RequesterError`** — upstream/third-party service returned an error (maps to 502)
+
+Key design choices:
+
+- **Static trace codes:** each error instance carries a `traceCode` (e.g., `USR_001`) that is grep-searchable across the codebase, enabling instant error origin identification in logs and monitoring
+- **`debugInformation` separation:** debug context (stack traces, internal state) is attached to the error but excluded from production API responses via the exception filter, preventing information leakage
+- **Transport-agnostic mapping:** the global exception filter maps `ApplicationError` subclasses to HTTP status codes; a separate gRPC or message handler filter can map the same errors to its own status codes
+
+## Consequences
+
+### Positive
+
+- Domain services remain transport-agnostic and reusable across HTTP, gRPC, and message consumers
+- Trace codes enable instant error location via `grep -r "USR_001"` across the entire codebase
+- Debug information is available in development and logging but never leaked to API consumers in production
+- Type-safe error handling — callers can catch specific error types rather than checking status codes
+
+### Negative
+
+- Additional class hierarchy to maintain alongside NestJS built-in exceptions
+- Developers must remember to throw `ApplicationError` subclasses instead of `HttpException`
+- Exception filter mapping logic must be kept in sync with new error types
+
+### Risks
+
+- Inconsistent adoption — mitigated by ESLint rule banning direct `HttpException` usage in service files
+
+## References
+
+- ADR-002: RFC 9457 Problem Details for Error Responses
+- Package: `@nestjs/common` (exception filters)

package/templates/base/docs/adr/024-request-context-pattern.md

@@ -0,0 +1,57 @@
+# ADR-024: Request Context via AsyncLocalStorage (CLS)
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-01
+
+## Context
+
+Cross-cutting request data (correlation ID, authenticated user, tenant ID) must be available throughout the call chain — in services, repositories, interceptors, and event handlers. Two approaches exist in NestJS: REQUEST-scoped injection and continuation-local storage (CLS) via `AsyncLocalStorage`.
+
+REQUEST-scoped providers force NestJS to create new instances of every dependent provider per request. This causes significant memory pressure and GC overhead under load, as the entire dependency subtree becomes request-scoped (the "scope bubble" problem).
+
+## Decision
+
+Use `nestjs-cls` (backed by Node.js `AsyncLocalStorage`) to propagate request context. Key design choices:
+
+- **CLS store initialization:** a `ClsMiddleware` runs first in the middleware chain, creating the store and generating a correlation ID (from `x-correlation-id` header or UUID)
+- **User and tenant enrichment:** a `ClsGuard` or interceptor populates `cls.set('user', ...)` and `cls.set('tenantId', ...)` after authentication
+- **Access pattern:** services inject `ClsService` and call `cls.get('correlationId')` — no constructor parameters, no method parameter drilling
+- **All providers remain DEFAULT scope:** no provider needs REQUEST scope, preserving singleton performance characteristics
+
+## Consequences
+
+### Positive
+
+- Zero memory overhead per request — all providers remain singleton-scoped
+- Correlation ID, user, and tenant are available anywhere in the call chain without parameter passing
+- Works across async boundaries including `Promise.all`, `setTimeout`, and event emitters
+- Compatible with Pino's request-scoped logging (ADR-017) — same correlation ID in both systems
+
+### Negative
+
+- `AsyncLocalStorage` is an implicit dependency — harder to trace data flow than explicit parameters
+- CLS context is lost across worker threads and child processes unless explicitly propagated
+- Developers unfamiliar with CLS may find the "magic" context confusing
+
+### Risks
+
+- CLS context loss in edge cases (native addons, some ORMs with custom connection pools) — mitigated by integration tests verifying context propagation
+
+## Alternatives Considered
+
+### REQUEST-scoped providers
+
+- **Pros:** native NestJS pattern, explicit dependency injection
+- **Cons:** every dependent provider becomes request-scoped, creating new instances per request; 30-50% throughput reduction in benchmarks
+- **Why not:** performance cost is unacceptable for high-throughput services
+
+## References
+
+- Package: `nestjs-cls`
+- Node.js API: `AsyncLocalStorage`
+- ADR-017: Structured JSON Logging with Pino

package/templates/base/docs/adr/025-data-patterns.md

@@ -0,0 +1,58 @@
+# ADR-025: Opt-in Data Patterns (Soft Delete, Audit Trail, Outbox)
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-01
+
+## Context
+
+Production applications frequently need soft delete (logical deletion without data loss), audit trails (who changed what and when), and guaranteed event delivery (outbox pattern). These are cross-cutting concerns that not every service or entity needs — mandating them globally would add unnecessary complexity and storage overhead to simple CRUD entities.
+
+## Decision
+
+Provide each data pattern as a separate opt-in recipe that can be applied per entity or globally:
+
+### Soft Delete
+
+- TypeORM `@DeleteDateColumn()` on entities needing logical deletion; `softDelete(id)` / `restore(id)`
+- Global query filter excludes soft-deleted rows by default; `withDeleted()` to include them
+
+### Audit Trail
+
+- `AuditInterceptor` captures entity snapshots before and after mutations, storing diffs in `audit_log`
+- User context sourced from CLS (ADR-024); configurable per entity via `@Auditable()` decorator
+
+### Transactional Outbox
+
+- Events written to an `outbox` table in the same database transaction as the business write
+- A poller or CDC process reads the outbox and publishes to the broker, preventing dual-write inconsistency
+
+## Consequences
+
+### Positive
+
+- Each pattern is independently adoptable — no all-or-nothing commitment
+- Soft delete preserves data for compliance and recovery without backup restores
+- Audit trail provides a complete change history for regulatory and debugging purposes
+- Outbox pattern eliminates the distributed transaction problem for event-driven architectures
+
+### Negative
+
+- Soft delete increases table sizes and requires `withDeleted()` awareness in queries
+- Audit trail adds write amplification — every mutation produces an additional insert
+- Outbox poller introduces publication latency (configurable polling interval)
+
+### Risks
+
+- Soft-deleted data accumulating indefinitely — mitigated by scheduled cleanup jobs for records past retention period
+- Outbox table growing under high write throughput — mitigated by immediate deletion after successful publish
+
+## References
+
+- ADR-003: Database Strategy
+- ADR-024: Request Context via AsyncLocalStorage (CLS)
+- Pattern reference: microservices.io/patterns/data/transactional-outbox

package/templates/base/docs/adr/026-migration-strategy.md

@@ -0,0 +1,57 @@
+# ADR-026: Database Migration Strategy (Lambda Runner Pattern)
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-01
+
+## Context
+
+Database migrations in serverless deployments cannot run via traditional CLI commands (`typeorm migration:run`) because there is no persistent server process. Migrations must execute before the application starts serving traffic, with validation that they succeeded. Running migrations at application startup is risky — multiple concurrent Lambda instances could race on the same migration.
+
+## Decision
+
+Use a dedicated migration-runner Lambda function that executes database migrations as a discrete pipeline step. Key design choices:
+
+- **Pipeline integration:** deploy migration-runner Lambda, invoke it, validate exit code, then deploy the application Lambda. If migration fails, the pipeline halts before the new application code is deployed
+- **ORM-agnostic architecture:** the migration runner is a thin wrapper that calls the ORM's migration API programmatically (`dataSource.runMigrations()` for TypeORM) rather than shelling out to CLI commands
+- **Barrel file pattern:** TypeORM with esbuild/Lambda requires explicit migration imports via a barrel file (`migrations/index.ts` re-exporting all migration classes) because esbuild cannot resolve TypeORM's glob-based migration discovery
+- **Local dev CLI:** developers use the standard `typeorm migration:run` CLI locally; the Lambda handler and CLI entrypoint share the same `DataSource` configuration but have separate entrypoints
+- **Idempotency:** TypeORM's migration table (`migrations`) tracks executed migrations; re-invoking the runner is safe
+
+## Consequences
+
+### Positive
+
+- Migrations run exactly once before application deployment — no race conditions from concurrent instances
+- Pipeline can gate deployment on migration success, preventing schema-code mismatches
+- Same migration code runs locally (CLI) and in production (Lambda) — no environment-specific migration logic
+- Barrel file pattern works reliably with esbuild tree-shaking and bundling
+
+### Negative
+
+- Additional Lambda function to deploy and maintain
+- Barrel file must be manually updated when adding new migrations (or automated via codegen script)
+- Pipeline is slightly slower due to the additional deploy-invoke-validate step
+
+### Risks
+
+- Migration timeout on large tables — mitigated by setting Lambda timeout to 15 minutes and using batched DDL operations
+- Barrel file drift (missing migration) — mitigated by a CI check that verifies all migration files are re-exported
+
+## Alternatives Considered
+
+### Run migrations at application startup
+
+- **Pros:** simpler deployment, no extra Lambda
+- **Cons:** race conditions with multiple instances, startup latency, failed migration leaves app in broken state
+- **Why not:** unsafe in multi-instance serverless environments
+
+## References
+
+- ADR-003: Database Strategy
+- ADR-005: Deployment Strategy
+- ADR-014: Build Toolchain

package/templates/base/docs/adr/027-dependency-management.md

@@ -0,0 +1,60 @@
+# ADR-027: Dependency Management with pnpm
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-01
+
+## Context
+
+Node.js package managers (npm, yarn, pnpm) differ significantly in installation speed, disk usage, dependency resolution strictness, and monorepo support. The boilerplate needs a package manager that supports the monorepo workspace layout (ADR-012), enforces strict dependency boundaries, and prevents phantom dependencies.
+
+## Decision
+
+Use **pnpm** as the sole package manager for all projects scaffolded by the boilerplate. Key design choices:
+
+- **Strict mode:** pnpm's default content-addressable store and symlink-based `node_modules` prevent phantom dependencies (packages that work by accident because a transitive dependency hoisted them)
+- **Exact versions:** `.npmrc` includes `save-exact=true` so `pnpm add` writes exact versions (e.g., `4.18.2` not `^4.18.2`), preventing unexpected minor/patch updates
+- **Workspace support:** `pnpm-workspace.yaml` defines the monorepo package topology; `workspace:*` protocol for internal package references
+- **Lockfile integrity:** `pnpm-lock.yaml` is committed and CI runs `pnpm install --frozen-lockfile` to ensure reproducible installs
+- **Automated updates:** Renovate or Dependabot configuration is provided as a recipe, configured to open PRs with exact version bumps on a weekly schedule
+- **Security auditing:** pre-push hook runs `pnpm audit --audit-level=high` to catch known vulnerabilities before code reaches the remote
+
+## Consequences
+
+### Positive
+
+- Content-addressable store saves disk space via shared package cache across projects
+- Strict `node_modules` layout catches missing `dependencies` declarations that npm/yarn silently resolve
+- Exact versions eliminate drift between development, CI, and production environments
+
+### Negative
+
+- Some packages with native bindings may need `pnpm.overrides` or `pnpm.patchedDependencies`
+- Developers accustomed to npm/yarn need to adopt pnpm-specific commands
+
+### Risks
+
+- pnpm adoption is lower than npm — mitigated by pnpm's growing ecosystem support and corepack integration in Node.js
+
+## Alternatives Considered
+
+### npm
+
+- **Pros:** default with Node.js, universal familiarity
+- **Cons:** flat `node_modules` allows phantom dependencies, slower installs, weaker workspace support
+- **Why not:** phantom dependencies cause production failures that are difficult to diagnose
+
+### yarn (v3+)
+
+- **Pros:** Plug'n'Play for zero-install, good workspace support
+- **Cons:** PnP mode has compatibility issues with many packages, complex configuration
+- **Why not:** pnpm achieves similar benefits with better compatibility
+
+## References
+
+- ADR-012: Monorepo Strategy
+- Configuration: `.npmrc`, `pnpm-workspace.yaml`

package/templates/base/docs/adr/028-code-quality-toolchain.md

@@ -0,0 +1,60 @@
+# ADR-028: Code Quality Toolchain (ESLint, Prettier, Commitlint, Husky)
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-01
+
+## Context
+
+Code quality enforcement via manual review is inconsistent and slow. Automated tooling must catch formatting, lint, commit message, and type errors before code reaches the remote. The toolchain must be fast enough that developers do not bypass it.
+
+## Decision
+
+Use a layered git hook pipeline with ESLint flat config, Prettier, commitlint, lint-staged, and husky:
+
+### Pre-commit (lint-staged)
+
+- **ESLint** on staged `.ts` files (flat config) + **Prettier** on staged files (TS, JSON, YAML, MD)
+- lint-staged processes only staged files, keeping the hook under 5 seconds
+
+### Commit-msg (commitlint)
+
+- Enforces Conventional Commits: `<type>(<scope>): <description>`, kebab-case scope, lowercase description
+
+### Pre-push
+
+- `tsc --noEmit` + `pnpm test` — type-check and unit tests must pass
+- Branch name validation enforces naming convention (`feature/`, `fix/`, `chore/`, etc.)
+
+## Consequences
+
+### Positive
+
+- Zero formatting debates — Prettier is the single source of truth
+- Consistent commit history enables automated changelog generation and semantic versioning
+- Type errors and test failures caught before push prevent broken CI builds
+
+### Negative
+
+- Five tools to configure; pre-push hook adds 10-30 seconds that developers may perceive as friction
+
+### Risks
+
+- Developers bypassing hooks with `--no-verify` — mitigated by CI running the same checks, so bypassed commits fail in pipeline
+
+## Alternatives Considered
+
+### Biome (formerly Rome)
+
+- **Pros:** single tool for linting and formatting, faster than ESLint + Prettier
+- **Cons:** smaller plugin ecosystem, no commitlint equivalent
+- **Why not:** ESLint's plugin ecosystem (TypeORM, NestJS-specific rules) is essential
+
+## References
+
+- ADR-009: Standards Compliance
+- Packages: `eslint`, `prettier`, `@commitlint/cli`, `lint-staged`, `husky`

package/templates/base/docs/adr/029-admin-panel.md

@@ -0,0 +1,53 @@
+# ADR-029: AdminJS as Admin Panel Recipe
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-01
+
+## Context
+
+Most backend applications eventually need an admin panel for data inspection, manual corrections, and operational tasks. Building a custom admin UI is expensive and rarely differentiated — the effort is better spent on the core product. The admin panel must integrate with the existing ORM and authentication without requiring a separate frontend deployment.
+
+## Decision
+
+Provide AdminJS as an opt-in recipe for auto-generated admin panels. Key design choices:
+
+- **Auto-generated CRUD:** AdminJS introspects ORM entity metadata to generate list, show, create, edit, and delete views with filtering, sorting, and pagination — no manual form definitions required
+- **ORM adapter pattern:** the recipe uses `@adminjs/typeorm` by default; adapters exist for Prisma (`@adminjs/prisma`), Mongoose (`@adminjs/mongoose`), and MikroORM (`@adminjs/mikroorm`), matching the boilerplate's ORM-agnostic philosophy
+- **NestJS integration:** `@adminjs/nestjs` mounts AdminJS as a NestJS module at `/admin`, sharing the application's dependency injection container and middleware pipeline
+- **Authentication:** environment-based credentials (`ADMIN_EMAIL`, `ADMIN_PASSWORD`) for simplicity in development and staging; production deployments should integrate with the application's auth system (ADR-004)
+- **Customization escape hatches:** custom actions, components, and dashboard widgets can be added per-resource without ejecting from the framework
+
+### When to use AdminJS vs custom admin
+
+- **Use AdminJS:** internal data browsing, support team tools, content management, entity CRUD operations
+- **Build custom:** customer-facing dashboards, complex multi-step workflows, real-time data visualization, highly branded experiences
+
+## Consequences
+
+### Positive
+
+- Admin panel available in minutes rather than weeks of custom development
+- Entity schema changes automatically reflected in the admin UI — no form maintenance
+- Single deployment — admin panel runs within the NestJS application process
+- ORM adapter swap requires only changing the adapter package, not rewriting admin configuration
+
+### Negative
+
+- AdminJS bundles a React frontend that increases the application's dependency footprint
+- Customization beyond standard CRUD requires learning AdminJS's component API
+- Performance may degrade with very large datasets without explicit pagination configuration
+
+### Risks
+
+- Security exposure if admin routes are not properly protected — mitigated by authentication guard and network-level access controls (VPN, IP allowlist)
+
+## References
+
+- ADR-003: Database Strategy
+- ADR-004: Authentication Architecture
+- Packages: `adminjs`, `@adminjs/nestjs`, `@adminjs/typeorm`

package/templates/base/docs/adr/030-performance-patterns.md

@@ -0,0 +1,60 @@
+# ADR-030: Performance Patterns (Workers, Circuit Breaker, Caching, Load Testing)
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-01
+
+## Context
+
+Node.js is single-threaded — CPU-intensive operations block the event loop and degrade throughput. External service calls can cascade failures when a dependency is unavailable. Without load testing, performance regressions reach production undetected.
+
+## Decision
+
+Provide a set of performance recipes that address common bottlenecks:
+
+### Worker Threads for CPU-intensive tasks
+
+- Use `worker_threads` for operations exceeding 50ms CPU time (PDF generation, image processing, CSV parsing)
+- `WorkerPool` manages reusable workers; communication via `MessagePort` with serializable data only
+
+### Circuit Breaker (opossum)
+
+- Wrap external calls with `opossum`; open after 5 failures in 30s, half-open retry after 10s
+- Fallback functions provide degraded responses when circuit is open; state changes emit monitoring events
+
+### Connection Pool Sizing and ETags
+
+- Database pool: `(CPU cores * 2) + 1` baseline; HTTP clients: `keepAlive: true` with bounded `maxSockets`
+- `EtagInterceptor` returns `304 Not Modified` for unchanged responses, reducing bandwidth
+
+### Request Timeout and Load Testing
+
+- Global timeout middleware (default 30s) returns `408` with Problem Details response (ADR-002)
+- k6 scripts in `test/load/` for smoke, load, stress, and soak scenarios; smoke tests run per PR in CI
+
+## Consequences
+
+### Positive
+
+- Worker threads keep the event loop responsive during CPU-intensive operations
+- Circuit breakers prevent cascade failures; ETags reduce bandwidth costs
+- k6 integration catches performance regressions before production deployment
+
+### Negative
+
+- Worker pool adds memory overhead (each worker is a separate V8 isolate)
+- Circuit breaker thresholds require per-dependency tuning
+
+### Risks
+
+- Misconfigured circuit breaker thresholds — mitigated by monitoring alerts on circuit state changes
+
+## References
+
+- ADR-002: RFC 9457 Problem Details for Error Responses
+- ADR-017: Structured JSON Logging with Pino
+- Packages: `opossum`, `k6`; Node.js API: `worker_threads`

package/templates/base/docs/adr/031-nx-generators-roadmap.md

@@ -0,0 +1,73 @@
+# ADR-031: Nx Generators for Post-Scaffolding Recipe Management
+
+## Status
+
+Proposed
+
+## Date
+
+2026-05-12
+
+## Context
+
+The current `spoonfeeder` CLI generates projects with selected recipes at creation time. However, teams frequently need to add recipes after project creation (e.g., adding Swagger to an existing API, adding Redis caching mid-project). Currently this requires manual integration.
+
+Nx Generators can modify existing TypeScript files safely using AST transforms, making it possible to:
+
+- Add a recipe to an existing project (`nx g spoonfeeder:add-recipe swagger`)
+- Remove a recipe (`nx g spoonfeeder:remove-recipe pino`)
+- Migrate between recipes (`nx g spoonfeeder:migrate-orm typeorm-postgres drizzle-postgres`)
+
+## Decision
+
+Explore Nx Generators as a second phase for recipe management. The current generate-and-own approach remains for project creation. Nx Generators would complement it for in-project modifications.
+
+## Consequences
+
+### Positive
+
+- Teams can add recipes incrementally as needs evolve
+- AST transforms safely modify imports, module registrations, and providers
+- Nx's virtual filesystem stages changes atomically (all-or-nothing)
+- Generators can run in dry-run mode for previewing changes
+- Pairs naturally with our existing Nx support for monorepo/full-stack types
+
+### Negative
+
+- Significant development effort (AST manipulation is complex)
+- Requires Nx as a project dependency (even for standalone apps)
+- Must handle all ORM/framework variations in transform logic
+- Testing generators requires snapshot testing of file transforms
+
+### Implementation Approach
+
+1. **Phase 1:** Recipe generators that add files + update package.json (no AST)
+2. **Phase 2:** Smart generators that modify app.module.ts imports and registrations
+3. **Phase 3:** Migration generators between recipes (e.g., TypeORM → Drizzle)
+
+### Technology
+
+- `@nx/devkit` — Generator API with Tree (virtual filesystem), `generateFiles`, `updateJson`
+- `ts-morph` — TypeScript AST manipulation for modifying source files
+- `@nx/nest` — Reference implementation for NestJS-specific generators
+
+## Alternatives Considered
+
+### Plop.js
+
+- **Pros:** Simple, Handlebars templates, low learning curve
+- **Cons:** Cannot modify existing files, only generates new ones
+- **Why not:** Doesn't solve the core problem (modifying app.module.ts, package.json)
+
+### Custom AST scripts
+
+- **Pros:** No framework dependency
+- **Cons:** Reimplements what Nx already provides (virtual filesystem, atomic commits, dry-run)
+- **Why not:** Nx is already in our stack for monorepo/full-stack types
+
+## References
+
+- [Nx Generator Documentation](https://nx.dev/extending-nx/intro/getting-started)
+- [@nx/devkit API](https://nx.dev/nx-api/devkit)
+- [ts-morph](https://ts-morph.com/)
+- [Creating Custom Nx Generators](https://blog.nrwl.io/create-a-custom-nx-workspace-generator-5a915d845fd)