spoonfeeder 0.1.0

package/templates/base/docs/adr/009-standards-compliance.md

@@ -0,0 +1,54 @@
+# ADR-009: RFC and Standards Compliance by Default
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-10
+
+## Context
+
+APIs built without standards compliance create integration friction for consumers, fail security audits, and require rework when standards are eventually adopted. Retrofitting RFC compliance is expensive.
+
+## Decision
+
+Implement key RFCs and open standards in the base template and recipes:
+
+**Base template (every project):**
+
+- RFC 9457 — Problem Details error responses (`application/problem+json`)
+- RFC 9110 — ETags via `@fastify/etag`
+- Graceful shutdown hooks
+- Request timeout middleware
+
+**Via recipes:**
+
+- RFC 8288 — Link headers for pagination
+- RFC 9111 — Cache-Control headers
+- RFC 7240 — Prefer header
+- RFC 7662 — OAuth 2.0 Token Introspection
+- RFC 9449 — DPoP proof-of-possession
+- RFC 9530 — Content Digest integrity
+- RFC 6902/7396 — JSON Patch / JSON Merge Patch
+- W3C Trace Context — via OpenTelemetry
+- OWASP API Security Top 10 — via security recipes
+
+## Consequences
+
+### Positive
+
+- API consumers get predictable, standardized responses
+- Error responses parse correctly in any RFC 9457-aware client
+- ETags reduce bandwidth by enabling conditional requests
+- Security headers (Helmet, CORS, CSRF) pass audit checklists
+
+### Negative
+
+- Slightly larger response payloads (RFC 9457 has more fields than a minimal error)
+- Teams must understand the standards to use extensions correctly
+
+## References
+
+- [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457)

package/templates/base/docs/adr/010-ai-context-generation.md

@@ -0,0 +1,44 @@
+# ADR-010: AI Assistant Context Generation
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-15
+
+## Context
+
+Modern development teams use AI coding assistants (Claude Code, Cursor, GitHub Copilot). These tools perform better when given project-specific context about patterns, conventions, and available APIs.
+
+## Decision
+
+Generate AI context files for three assistants as part of project scaffolding:
+
+- **CLAUDE.md** — Project-level instructions for Claude Code (package manager, imports, testing, commands, active recipes)
+- **.cursor/rules/\*.mdc** — Cursor rules for framework-specific patterns (NestJS backend, React/Vue/Svelte frontend)
+- **.github/copilot-instructions.md** — GitHub Copilot project instructions
+
+Context is assembled from:
+
+1. Base instructions (common to all projects)
+2. Recipe-specific sections (each recipe contributes its own context)
+3. Frontend framework rules (for full-stack projects)
+
+## Consequences
+
+### Positive
+
+- AI assistants understand project conventions immediately
+- Recipe-specific context prevents AI from suggesting patterns that conflict with selected tools
+- Frontend-specific rules guide AI on framework idioms (Server Components in Next.js, Composition API in Vue, etc.)
+
+### Negative
+
+- Context files add ~20-30 lines per recipe to CLAUDE.md
+- Teams using other AI tools (Windsurf, Cody) don't benefit without manual adaptation
+
+### Risks
+
+- AI context becoming stale as patterns evolve — mitigated by keeping context co-located with recipe templates

package/templates/base/docs/adr/011-package-versioning.md

@@ -0,0 +1,44 @@
+# ADR-011: Exact Dependency Versions (No Ranges)
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-20
+
+## Context
+
+npm defaults to caret ranges (`^1.2.3`) which allow minor and patch updates. While this sounds convenient, it has caused production incidents when a patch release introduced breaking changes or was compromised (supply chain attack).
+
+## Decision
+
+Pin all dependency versions to exact values (`1.2.3`, not `^1.2.3`). Enforce via:
+
+- `.npmrc` with `save-exact=true`
+- Pre-commit hook checking for version ranges
+- `pnpm install -E` for all package installations
+
+## Consequences
+
+### Positive
+
+- **Reproducible builds** — Same versions in dev, CI, staging, and production
+- **Security** — No automatic adoption of compromised patch releases
+- **Auditability** — Every version change is an explicit commit with a changelog review
+- **No surprises** — Builds never break from upstream changes
+
+### Negative
+
+- Manual dependency updates required (no automatic patch adoption)
+- More frequent dependency update PRs
+- Lockfile churn when updating multiple packages
+
+### Risks
+
+- Missing security patches — mitigated by Dependabot/Renovate recipe and `pnpm audit` in CI
+
+## References
+
+- `CLAUDE.md` (project root) — "NEVER use version ranges"

package/templates/base/docs/adr/012-monorepo-strategy.md

@@ -0,0 +1,54 @@
+# ADR-012: Nx for Monorepo and Full-Stack Project Types
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+Monorepo and full-stack project types need workspace management: shared libraries, task orchestration, dependency graph awareness, and caching.
+
+Options: pnpm workspaces only, Nx, Turborepo, Lerna.
+
+## Decision
+
+Use Nx with pnpm workspaces for monorepo and full-stack project types.
+
+## Consequences
+
+### Positive
+
+- First-class NestJS plugin (`@nx/nest`) with generators matching NestJS schematics
+- Task caching (local + remote) saves CI time as the workspace grows
+- `nx affected` runs only changed projects
+- Dependency graph visualization (`nx graph`)
+
+### Negative
+
+- Additional learning curve for teams unfamiliar with Nx
+- Nx adds ~50MB to node_modules
+- Configuration overhead for small projects
+
+### Alternatives Considered
+
+#### pnpm workspaces only
+
+- **Pros:** Minimal tooling, no extra dependencies
+- **Cons:** No task caching, no dependency graph, no affected commands
+- **Why not:** Missing features that matter at scale (5+ packages)
+
+#### Turborepo
+
+- **Pros:** Simpler than Nx, good task caching
+- **Cons:** Less NestJS-specific tooling, no generators
+- **Why not:** Nx has better NestJS integration
+
+#### Lerna
+
+- **Pros:** Well-known
+- **Cons:** Now powered by Nx under the hood, adds an unnecessary layer
+- **Why not:** Just use Nx directly

package/templates/base/docs/adr/013-http-adapter.md

@@ -0,0 +1,63 @@
+# ADR-013: Fastify as Default HTTP Adapter
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+NestJS supports two HTTP adapters: Express (`@nestjs/platform-express`) and Fastify (`@nestjs/platform-fastify`). The choice of adapter affects request throughput, plugin architecture, and middleware compatibility across all scaffolded projects.
+
+## Decision
+
+Use Fastify as the default HTTP adapter for all project types that handle HTTP traffic (HTTP API, Full-Stack, Lambda). Provide an `express-adapter` recipe for teams that require Express middleware compatibility.
+
+The base template configures Fastify in `main.ts`:
+
+```ts
+const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
+```
+
+## Consequences
+
+### Positive
+
+- 2-3x higher throughput than Express in synthetic benchmarks (JSON serialization, route matching)
+- Schema-based request validation via Fastify's built-in JSON Schema support
+- Encapsulated plugin system prevents global state leaks between modules
+- First-class TypeScript support with typed request/reply objects
+- Fastify v5 lifecycle hooks align well with NestJS interceptors and guards
+
+### Negative
+
+- Express middleware packages (e.g., `express-session`, `passport` strategies using `req`/`res` directly) require the `@fastify/middie` compatibility layer or Fastify-native alternatives
+- Smaller plugin ecosystem compared to Express — some niche middleware has no Fastify equivalent
+- Developers familiar only with Express face a minor learning curve for Fastify's plugin model
+
+### Risks
+
+- Breaking changes in Fastify major versions — mitigated by exact version pinning and the scaffolder's dependency audit workflow
+
+## Alternatives Considered
+
+### Express (default)
+
+- **Pros:** Largest middleware ecosystem, most developer familiarity
+- **Cons:** Slower request handling, callback-oriented internals, no built-in schema validation
+- **Why not:** Performance cost is measurable at scale; available as the `express-adapter` recipe for teams that need it
+
+### Koa / Hono
+
+- **Pros:** Lightweight, modern API design
+- **Cons:** No official NestJS adapter, no DI integration
+- **Why not:** NestJS only ships adapters for Express and Fastify
+
+## References
+
+- [Fastify Benchmarks](https://fastify.dev/benchmarks/)
+- [NestJS Performance (Fastify)](https://docs.nestjs.com/techniques/performance)
+- Recipe: `express-adapter`

package/templates/base/docs/adr/014-build-toolchain.md

@@ -0,0 +1,61 @@
+# ADR-014: SWC as Default Build Toolchain
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+TypeScript projects require a compilation step from TS to JS. The default `tsc` compiler is correct but slow, especially in large monorepos. NestJS v10+ ships with first-class SWC support via `@swc/core` and the `nest build --builder swc` flag.
+
+## Decision
+
+Use SWC (`@swc/core`) as the default TypeScript compiler for both builds and tests. The toolchain consists of:
+
+- **Build:** `nest build --builder swc` via `@nestjs/cli` with SWC builder
+- **Tests:** `@swc/jest` as the Jest transform, configured in `jest.config.ts`
+- **Path aliases:** `tsc-alias` as a post-build step to resolve `@/*` path mappings in emitted JS
+- **Type checking:** `tsc --noEmit` run separately in CI (SWC does not type-check)
+
+## Consequences
+
+### Positive
+
+- 10-20x faster compilation than `tsc` for incremental builds
+- Jest test suites start significantly faster with `@swc/jest` (no `ts-jest` overhead)
+- SWC supports TypeScript 5 decorators and `emitDecoratorMetadata` via `@swc/core` plugins
+- NestJS CLI has native SWC integration — no custom webpack config needed
+- Hot Module Replacement (HMR) in `start:dev` is near-instant
+
+### Negative
+
+- SWC does not perform type checking — requires a separate `tsc --noEmit` step in CI
+- Some edge-case TypeScript features (const enums across files, composite projects) need workarounds
+- `tsc-alias` adds a post-build step for path alias resolution
+
+### Risks
+
+- Decorator metadata divergence between SWC and tsc — mitigated by testing DI resolution in integration tests
+
+## Alternatives Considered
+
+### tsc (TypeScript Compiler)
+
+- **Pros:** Official compiler, type checking included, zero config
+- **Cons:** 10-20x slower builds, slower test startup
+- **Why not:** Build speed directly impacts developer experience and CI costs
+
+### esbuild
+
+- **Pros:** Extremely fast, Go-based
+- **Cons:** No decorator metadata support, no NestJS CLI integration
+- **Why not:** NestJS depends on `emitDecoratorMetadata` for DI; esbuild cannot emit it
+
+## References
+
+- [NestJS SWC Builder](https://docs.nestjs.com/recipes/swc)
+- Packages: `@swc/core`, `@swc/jest`, `tsc-alias`

package/templates/base/docs/adr/015-cloud-provider-strategy.md

@@ -0,0 +1,49 @@
+# ADR-015: Multi-Cloud Support via Composable Recipes
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+Teams deploy to different cloud providers depending on organizational standards. Locking the boilerplate to a single provider (e.g., AWS-only) would exclude a large portion of users and create vendor lock-in at the template level.
+
+## Decision
+
+Support AWS, GCP, and Azure as first-class cloud providers through composable recipes. Each cloud service is wrapped in a dedicated NestJS module that injects configuration via `ConfigService` and exposes a provider-agnostic interface where practical.
+
+The CLI presents a `--cloud` flag (`aws`, `gcp`, `azure`) that pre-selects cloud-appropriate recipe defaults:
+
+- **AWS:** `aws-s3`, `aws-sqs`, `aws-ses`, `aws-secrets-manager`, `aws-lambda-deploy`
+- **GCP:** `gcp-cloud-storage`, `gcp-pub-sub`, `gcp-cloud-tasks`, `gcp-secret-manager`
+- **Azure:** `azure-blob-storage`, `azure-service-bus`, `azure-key-vault`
+
+Each cloud recipe declares conflicts with its counterparts (e.g., `aws-s3` conflicts with `gcp-cloud-storage`).
+
+## Consequences
+
+### Positive
+
+- Teams choose their cloud without forking the boilerplate
+- Cloud-aware CLI defaults reduce decision fatigue during scaffolding
+- Service modules use `ConfigService` for credentials — no hardcoded provider SDKs in business logic
+- Adding a new cloud service is a self-contained recipe contribution
+
+### Negative
+
+- Maintaining parity across three cloud providers multiplies recipe count
+- Provider-agnostic interfaces can leak abstractions for provider-specific features
+- Testing requires credentials or emulators for each cloud provider
+
+### Risks
+
+- SDK version drift across providers — mitigated by exact version pinning and per-provider CI test matrices
+
+## References
+
+- Recipe groups: `aws-*`, `gcp-*`, `azure-*`
+- ADR-008: Composable Recipe System

package/templates/base/docs/adr/016-ci-cd-pipeline-strategy.md

@@ -0,0 +1,52 @@
+# ADR-016: Multi-Provider CI/CD Pipeline Strategy
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+Organizations standardize on different CI/CD platforms depending on their cloud provider and existing tooling. A boilerplate that only generates GitHub Actions workflows excludes teams on Azure DevOps, AWS, or GCP-native pipelines.
+
+## Decision
+
+Support four CI/CD providers via recipes: GitHub Actions, Azure DevOps Pipelines, AWS CodePipeline, and GCP Cloud Build. All providers implement the same standardized pipeline stages:
+
+1. **Install** — dependency installation with lockfile caching
+2. **Lint & Format** — ESLint + Prettier checks
+3. **Type Check** — `tsc --noEmit`
+4. **Unit Test** — Jest with coverage thresholds
+5. **Build** — SWC compilation
+6. **Integration Test** — against real services (database, cache)
+7. **Docker Build** — multi-stage Dockerfile with layer caching
+8. **Deploy** — environment-specific deployment (dev/staging/prod)
+
+Database migrations run via a migration-runner Lambda (AWS) or equivalent serverless function that executes before the application deployment, ensuring schema changes are applied atomically and independently of the application lifecycle.
+
+## Consequences
+
+### Positive
+
+- Teams use their existing CI/CD platform without manual pipeline authoring
+- Standardized stages ensure consistent quality gates across all providers
+- Migration-runner pattern decouples schema changes from application deploys
+- Pipeline configs are generated with project-specific values (image names, regions, service names)
+
+### Negative
+
+- Four pipeline configurations to maintain and keep in sync
+- Provider-specific features (GitHub Actions marketplace, Azure DevOps service connections) are underutilized to maintain portability
+- Migration-runner adds an extra deployment artifact to manage
+
+### Risks
+
+- Pipeline syntax breaking changes in provider updates — mitigated by pinning action/task versions
+
+## References
+
+- Recipes: `github-actions`, `azure-devops`, `aws-codepipeline`, `gcp-cloud-build`
+- ADR-005: Deployment Strategy

package/templates/base/docs/adr/017-logging-strategy.md

@@ -0,0 +1,63 @@
+# ADR-017: Structured JSON Logging with Pino
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+Production applications need structured, machine-parseable logs for integration with cloud log aggregators (CloudWatch, Stackdriver, Azure Monitor). NestJS's default `ConsoleLogger` outputs unstructured text that is difficult to query, filter, and alert on.
+
+## Decision
+
+Use Pino (`nestjs-pino`) as the default logging library with structured JSON output. Key design choices:
+
+- **Request context propagation:** `nestjs-pino` auto-attaches a correlation ID (`x-correlation-id` header or generated UUID) to every log line within a request lifecycle via `AsyncLocalStorage`
+- **Log levels:** configurable via `LOG_LEVEL` environment variable (default: `info` in production, `debug` in development)
+- **Pretty printing:** `pino-pretty` enabled in development via `NODE_ENV` detection for human-readable output
+- **Redaction:** sensitive fields (`password`, `authorization`, `cookie`) are redacted from log output by default
+
+Winston is available as an alternative via the `winston-logger` recipe for teams with existing Winston infrastructure.
+
+## Consequences
+
+### Positive
+
+- JSON logs are natively queryable in all major cloud log aggregators
+- Correlation IDs enable end-to-end request tracing across services
+- Pino's low-overhead design (worker-thread serialization) has minimal impact on request latency
+- Automatic request/response logging via `nestjs-pino` middleware eliminates manual log calls
+
+### Negative
+
+- JSON output is harder to read in local development without `pino-pretty`
+- Pino's opinionated API differs from Winston — existing Winston log patterns need adaptation
+- Redaction configuration must be maintained as new sensitive fields are added
+
+### Risks
+
+- Log volume costs in cloud environments — mitigated by appropriate log level configuration and sampling
+
+## Alternatives Considered
+
+### Winston
+
+- **Pros:** Most popular Node.js logger, flexible transports, wide adoption
+- **Cons:** Higher overhead per log call, synchronous serialization, less NestJS integration
+- **Why not:** Pino's performance advantage matters for high-throughput services; Winston available via recipe
+
+### NestJS ConsoleLogger
+
+- **Pros:** Zero dependencies, built-in
+- **Cons:** Unstructured text, no correlation IDs, no JSON output
+- **Why not:** Unsuitable for production log aggregation
+
+## References
+
+- Packages: `nestjs-pino`, `pino`, `pino-pretty`, `pino-http`
+- Recipe: `winston-logger`
+- ADR-021: Observability Strategy

package/templates/base/docs/adr/018-security-architecture.md

@@ -0,0 +1,61 @@
+# ADR-018: Defense-in-Depth Security Architecture
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+APIs are exposed to the public internet and face a wide range of attack vectors. A single security mechanism is insufficient — the OWASP API Security Top 10 requires multiple layers of defense applied consistently across all scaffolded projects.
+
+## Decision
+
+Implement a defense-in-depth approach with the following layers enabled by default in the base template:
+
+| Layer            | Implementation                                             | OWASP Mapping |
+| ---------------- | ---------------------------------------------------------- | ------------- |
+| Security headers | `@fastify/helmet`                                          | API1, API7    |
+| CORS             | `@fastify/cors` with explicit origin allowlist             | API7          |
+| CSRF protection  | `@fastify/csrf-protection` (stateful endpoints)            | API2          |
+| Rate limiting    | `@nestjs/throttler` with configurable windows              | API4          |
+| Input validation | `class-validator` + `class-transformer` on all DTOs        | API3, API8    |
+| Request timeouts | Fastify `connectionTimeout` + `requestTimeout`             | API4          |
+| Payload limits   | Fastify `bodyLimit` (default 1MB)                          | API4          |
+| SSRF prevention  | URL allowlist validation in HTTP-calling services          | API7          |
+| Content digest   | `content-digest` header verification for webhook receivers | API2          |
+
+Additional security recipes available:
+
+- `api-key-auth` — API key validation via custom guard
+- `oauth2` — OAuth 2.0 / OpenID Connect integration
+- `mTLS` — mutual TLS for service-to-service communication
+
+## Consequences
+
+### Positive
+
+- All projects start with a secure baseline — security is opt-out, not opt-in
+- OWASP API Security Top 10 coverage documented and mapped per control
+- `class-validator` decorators on DTOs enforce validation at the boundary, preventing injection
+- Rate limiting prevents brute-force and DoS attacks at the application layer
+
+### Negative
+
+- Default security controls may be too restrictive for internal-only APIs (CORS, CSRF)
+- Rate limiting configuration requires tuning per endpoint — defaults may not fit all use cases
+- Helmet's CSP defaults can break frontend assets if not configured correctly in full-stack projects
+
+### Risks
+
+- False sense of security — application-level controls do not replace network-level security (WAF, VPC)
+- Misconfigured CORS allowlists — mitigated by requiring explicit origins, rejecting `*` in production
+
+## References
+
+- [OWASP API Security Top 10](https://owasp.org/API-Security/)
+- Packages: `@fastify/helmet`, `@fastify/cors`, `@fastify/csrf-protection`, `@nestjs/throttler`, `class-validator`
+- ADR-004: Authentication Architecture

package/templates/base/docs/adr/019-project-type-design.md

@@ -0,0 +1,61 @@
+# ADR-019: Seven Project Types with Template Overlays
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+Not all backend applications are HTTP APIs. Teams build Lambda functions, CLI tools, background workers, and microservices. A single project template cannot serve all these use cases without shipping unnecessary boilerplate for each.
+
+## Decision
+
+Support seven project types, each with a distinct `main.ts` bootstrap, package fragment, and template overlay applied on top of the shared base template:
+
+| Project Type     | Bootstrap                                      | Transport                     | Key Packages                                  |
+| ---------------- | ---------------------------------------------- | ----------------------------- | --------------------------------------------- |
+| **HTTP API**     | `NestFactory.create(FastifyAdapter)`           | HTTP                          | `@nestjs/platform-fastify`                    |
+| **Lambda**       | `@codegenie/serverless-express` handler export | HTTP via API Gateway          | `@codegenie/serverless-express`, `aws-lambda` |
+| **Microservice** | `NestFactory.createMicroservice()`             | TCP / RabbitMQ / Kafka / gRPC | `@nestjs/microservices`                       |
+| **CLI**          | `nest-commander` bootstrap                     | stdin/stdout                  | `nest-commander`                              |
+| **Worker**       | `NestFactory.createApplicationContext()`       | Queue consumer                | `@nestjs/bullmq`, `bullmq`                    |
+| **Monorepo**     | Multiple apps with shared libs                 | Per-app                       | `@nestjs/cli` workspaces                      |
+| **Full-Stack**   | NestJS API + frontend framework                | HTTP + SSR/SPA                | Per-framework (see ADR-020)                   |
+
+The CLI presents project type selection as the first prompt. Each type determines:
+
+1. Which `main.ts` template to use
+2. Which package fragments to merge into `package.json`
+3. Which recipes are available (e.g., `aws-lambda-deploy` only for Lambda type)
+4. Which default recipes to pre-select
+
+Microservice transport is a sub-selection within the Microservice type, choosing between TCP, RabbitMQ (`@nestjs/microservices` + `amqplib`), Kafka (`kafkajs`), and gRPC (`@grpc/grpc-js`).
+
+## Consequences
+
+### Positive
+
+- Each project type ships only the dependencies and configuration it needs
+- New project types can be added without modifying the base template
+- Transport selection for microservices is explicit, not a hidden config option
+- Template overlays are composable with recipes for maximum flexibility
+
+### Negative
+
+- Seven project types increase scaffolder complexity and test surface
+- Some recipes are only valid for certain project types — requires type-aware recipe filtering
+- Monorepo type has significantly different directory structure than single-app types
+
+### Risks
+
+- Project type proliferation — mitigated by requiring an ADR for each new type
+
+## References
+
+- ADR-007: Scaffolder Architecture
+- ADR-008: Composable Recipe System
+- ADR-012: Monorepo Strategy

package/templates/base/docs/adr/020-frontend-framework-support.md

@@ -0,0 +1,57 @@
+# ADR-020: Frontend Framework Support for Full-Stack Projects
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-01
+
+## Context
+
+The Full-Stack project type (ADR-019) requires a frontend framework alongside the NestJS API. Teams have strong preferences for their frontend stack, and prescribing a single framework would limit adoption.
+
+## Decision
+
+Support four frontend frameworks as sub-selections within the Full-Stack project type:
+
+| Framework      | Package                      | Rendering       | Use Case                      |
+| -------------- | ---------------------------- | --------------- | ----------------------------- |
+| **Next.js**    | `next`, `react`, `react-dom` | SSR / SSG / ISR | SEO-critical apps, dashboards |
+| **Vite React** | `vite`, `react`, `react-dom` | SPA (CSR)       | Internal tools, admin panels  |
+| **Nuxt**       | `nuxt`, `vue`                | SSR / SSG       | Vue-based teams               |
+| **SvelteKit**  | `@sveltejs/kit`, `svelte`    | SSR / SSG       | Performance-focused apps      |
+
+Each framework selection generates:
+
+- **Proxy configuration:** API calls from the frontend dev server proxy to the NestJS API (e.g., Vite's `server.proxy`, Next.js rewrites)
+- **Directory structure:** `apps/web/` for the frontend, `apps/api/` for the NestJS backend
+- **AI context:** Framework-specific CLAUDE.md sections, `.cursor/rules`, and `.github/copilot-instructions.md`
+- **Build integration:** Unified `pnpm build` that compiles both frontend and API
+- **Docker configuration:** Multi-stage Dockerfile serving the frontend via the NestJS API or a separate container
+
+## Consequences
+
+### Positive
+
+- Teams use their preferred frontend framework without ejecting from the boilerplate
+- Proxy configuration eliminates CORS issues during local development
+- AI context per framework improves code generation quality in Cursor, Copilot, and Claude
+- Shared TypeScript types between frontend and API via monorepo workspace packages
+
+### Negative
+
+- Four frontend frameworks quadruple the frontend template maintenance burden
+- Framework-specific build quirks (Next.js standalone output, SvelteKit adapters) require per-framework Docker configs
+- Keeping AI context accurate across framework version updates is ongoing work
+
+### Risks
+
+- Framework deprecation or major API changes — mitigated by supporting only actively maintained frameworks with large communities
+
+## References
+
+- ADR-019: Project Type Design
+- ADR-010: AI Context Generation
+- ADR-012: Monorepo Strategy