@zigrivers/scaffold 3.6.0 → 3.8.0

package/README.md

@@ -29,7 +29,7 @@ Either way, Scaffold constructs the prompt and the target AI tool does the work.
 
 **Assembly engine** — At execution time, Scaffold builds a 7-section prompt from: system metadata, the meta-prompt, knowledge base entries, project context (artifacts from prior steps), methodology settings, layered instructions, and depth-specific execution guidance.
 
-**Knowledge base** — 60 domain expertise entries in `content/knowledge/` organized in seven categories (core, product, review, validation, finalization, execution, tools) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
+**Knowledge base** — 158 domain expertise entries in `content/knowledge/` organized in thirteen categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
 
 **Methodology presets** — Three built-in presets control which steps run and how deep the analysis goes:
 - **deep** (depth 5) — all steps enabled, exhaustive analysis
@@ -371,6 +371,52 @@ Every `scaffold init` wizard question can be answered via CLI flags, making scaf
 | `--project-type` | string | web-app, mobile-app, backend, cli, library, game |
 | `--auto` | boolean | Non-interactive mode (uses Zod defaults for unset flags) |
 
+#### Web-App Config Flags (require `--project-type web-app` or auto-set it)
+
+| Flag | Type | Values |
+|------|------|--------|
+| `--web-rendering` | string | spa, ssr, ssg, hybrid |
+| `--web-deploy-target` | string | static, serverless, container, edge, long-running |
+| `--web-realtime` | string | none, websocket, sse |
+| `--web-auth-flow` | string | none, session, oauth, passkey |
+
+#### Backend Config Flags (require `--project-type backend` or auto-set it)
+
+| Flag | Type | Values |
+|------|------|--------|
+| `--backend-api-style` | string | rest, graphql, grpc, trpc, none |
+| `--backend-data-store` | comma-sep | relational, document, key-value |
+| `--backend-auth` | string | none, jwt, session, oauth, apikey |
+| `--backend-messaging` | string | none, queue, event-driven |
+| `--backend-deploy-target` | string | serverless, container, long-running |
+
+#### CLI Config Flags (require `--project-type cli` or auto-set it)
+
+| Flag | Type | Values |
+|------|------|--------|
+| `--cli-interactivity` | string | args-only, interactive, hybrid |
+| `--cli-distribution` | comma-sep | package-manager, system-package-manager, standalone-binary, container |
+| `--cli-structured-output` | boolean | `--cli-structured-output` / `--no-cli-structured-output` |
+
+#### Library Config Flags (require `--project-type library` or auto-set it)
+
+| Flag | Type | Values |
+|------|------|--------|
+| `--lib-visibility` | string | public, internal |
+| `--lib-runtime-target` | string | node, browser, isomorphic, edge |
+| `--lib-bundle-format` | string | esm, cjs, dual, unbundled |
+| `--lib-type-definitions` | boolean | `--lib-type-definitions` / `--no-lib-type-definitions` |
+| `--lib-doc-level` | string | none, readme, api-docs, full-site |
+
+#### Mobile-App Config Flags (require `--project-type mobile-app` or auto-set it)
+
+| Flag | Type | Values |
+|------|------|--------|
+| `--mobile-platform` | string | ios, android, cross-platform |
+| `--mobile-distribution` | string | public, private, mixed |
+| `--mobile-offline` | string | none, cache, offline-first |
+| `--mobile-push-notifications` | boolean | `--mobile-push-notifications` / `--no-mobile-push-notifications` |
+
 #### Game Config Flags (require `--project-type game` or auto-set it)
 
 | Flag | Type | Values |
@@ -387,16 +433,66 @@ Every `scaffold init` wizard question can be answered via CLI flags, making scaf
 | `--modding` | boolean | `--modding` / `--no-modding` |
 | `--persistence` | string | none, settings-only, profile, progression, cloud |
 
+> **Flag aliases**: Game flags have `--game-*` aliases for consistency with other project types (e.g., `--game-engine` is equivalent to `--engine`). Bare flags like `--engine` still work.
+
 #### How Flags Interact
 
 - **Flag > auto > interactive**: Flags always take highest precedence. `--auto --engine unreal` uses defaults for everything except engine.
 - **Partial flags + interactive**: Provide some flags and the wizard asks only the remaining questions. `scaffold init --project-type game --engine unreal` prompts interactively for multiplayer, platforms, etc.
-- **Game flags auto-set project type**: `--engine unity` automatically sets `--project-type game`. Error if conflicting non-game type.
-- **Validation**: `--depth` requires `--methodology custom`. `--online-services` requires `--multiplayer online` or `hybrid`.
+- **Type-specific flags auto-set project type**: `--engine unity` automatically sets `--project-type game`, `--web-rendering ssr` sets `--project-type web-app`, `--backend-api-style rest` sets `--project-type backend`, `--cli-interactivity hybrid` sets `--project-type cli`, `--lib-visibility public` sets `--project-type library`, `--mobile-platform ios` sets `--project-type mobile-app`. Error if conflicting type.
+- **Cannot mix flag families**: `--web-rendering ssr --backend-api-style rest` is an error. Each flag family is exclusive.
+- **Validation**: `--depth` requires `--methodology custom`. `--online-services` requires `--multiplayer online` or `hybrid`. SSR/hybrid rendering is incompatible with static deploy target. Session auth requires server state (not static).
 
 #### CI Examples
 
 ```bash
+# Web-app project (SSR with serverless deploy)
+scaffold init --auto --methodology deep --project-type web-app \
+  --web-rendering ssr --web-deploy-target serverless
+
+# Web-app with real-time features and OAuth
+scaffold init --auto --methodology deep --project-type web-app \
+  --web-rendering ssr --web-deploy-target container \
+  --web-realtime websocket --web-auth-flow oauth
+
+# Backend project (GraphQL with relational + key-value stores)
+scaffold init --auto --methodology deep --project-type backend \
+  --backend-api-style graphql --backend-data-store relational,key-value
+
+# Backend with event-driven messaging and JWT auth
+scaffold init --auto --methodology deep --project-type backend \
+  --backend-api-style rest --backend-data-store relational \
+  --backend-auth jwt --backend-messaging event-driven \
+  --backend-deploy-target container
+
+# CLI project (interactive with multiple distribution channels)
+scaffold init --auto --methodology mvp --project-type cli \
+  --cli-interactivity hybrid --cli-distribution package-manager,standalone-binary
+
+# CLI with structured JSON output
+scaffold init --auto --methodology deep --project-type cli \
+  --cli-interactivity args-only --cli-distribution package-manager \
+  --cli-structured-output
+
+# Public library with full API docs and ESM bundle
+scaffold init --auto --methodology deep --project-type library \
+  --lib-visibility public --lib-runtime-target isomorphic \
+  --lib-bundle-format esm --lib-doc-level api-docs
+
+# Internal library (Node-only, no docs)
+scaffold init --auto --methodology mvp --project-type library \
+  --lib-visibility internal --lib-runtime-target node \
+  --lib-bundle-format cjs --lib-doc-level none
+
+# Cross-platform mobile app with offline support
+scaffold init --auto --methodology deep --project-type mobile-app \
+  --mobile-platform cross-platform --mobile-offline offline-first \
+  --mobile-push-notifications
+
+# iOS app with private distribution
+scaffold init --auto --methodology mvp --project-type mobile-app \
+  --mobile-platform ios --mobile-distribution private
+
 # Multiplayer mobile game with Unity
 scaffold init --project-type game --methodology deep --auto \
   --engine unity --multiplayer online --target-platforms ios,android \
@@ -405,10 +501,6 @@ scaffold init --project-type game --methodology deep --auto \
 # Simple puzzle game
 scaffold init --project-type game --auto --engine godot
 
-# Web app with multiple AI adapters
-scaffold init --project-type web-app --methodology mvp --auto \
-  --adapters claude-code,gemini --traits web,mobile
-
 # Custom methodology at depth 3
 scaffold init --methodology custom --depth 3 --auto
 
@@ -421,6 +513,25 @@ scaffold init --project-type game --methodology deep --auto \
   --content-structure open-world
 ```
 
+### Project-Type Overlays
+
+Scaffold supports **project-type overlays** — domain-specific knowledge and pipeline customizations that activate based on your project type. When you set a project type during `scaffold init`, the corresponding overlay layers on top of your chosen methodology (mvp, deep, or custom):
+
+- **Injects domain knowledge** into existing pipeline steps (e.g., SSR caching strategies into `tech-stack`, API pagination patterns into `coding-standards`)
+
+The game overlay additionally adjusts step enablement, remaps artifact references, and adds dependency overrides (because game development has fundamentally different artifacts). The web-app, backend, CLI, library, and mobile-app overlays are **knowledge-only** — they inject domain expertise into existing steps without changing which steps run or how they depend on each other.
+
+Overlays are composable with methodology presets. An MVP web-app gets fewer steps at lower depth; a deep backend project gets exhaustive analysis of every architectural decision.
+
+| Project Type | Overlay | Knowledge Entries | Config Options |
+|-------------|---------|-------------------|----------------|
+| `web-app` | `web-app-overlay.yml` | 17 entries (rendering, state management, auth, SSR, deploy targets, real-time, PWA, testing) | Rendering strategy, deploy target, real-time, auth flow |
+| `backend` | `backend-overlay.yml` | 14 entries (API design, data stores, auth, messaging, observability, deploy, caching, rate limiting) | API style, data store(s), auth, messaging, deploy target |
+| `cli` | `cli-overlay.yml` | 10 entries (argument parsing, config management, output formatting, distribution, testing, error handling) | Interactivity model, distribution channels, structured output |
+| `library` | `library-overlay.yml` | 12 entries (API design, bundling, type definitions, versioning, documentation, testing, security) | Visibility, runtime target, bundle format, type definitions, documentation level |
+| `mobile-app` | `mobile-app-overlay.yml` | 12 entries (architecture, offline patterns, push notifications, deployment, distribution, testing, security) | Platform, distribution model, offline support, push notifications |
+| `game` | `game-overlay.yml` | 24 entries (engines, networking, audio, VR/AR, economy, save systems, certification) | Engine, multiplayer, platforms, economy, narrative, and 6 more |
+
 ### Game Development
 
 Scaffold fully supports game development projects. When you select `game` as your project type, a **project-type overlay** activates 24 game-specific pipeline steps and injects game domain expertise into existing steps — all while keeping the standard pipeline workflow (status, next, rework, multi-model review) fully functional.
@@ -1113,15 +1224,19 @@ scaffold dashboard
 
 ## Knowledge System
 
-Scaffold ships with 60 domain expertise entries organized in seven categories:
+Scaffold ships with 134 domain expertise entries organized in eleven categories:
 
-- **core/** (25 entries) — eval craft, testing strategy, domain modeling, API design, database design, system architecture, ADR craft, security best practices, operations, task decomposition, user stories, UX specification, design system tokens, user story innovation, AI memory management, coding conventions, tech stack selection, project structure patterns, task tracking, CLAUDE.md patterns, multi-model review dispatch, review step template, dev environment, git workflow patterns, automated review tooling
-- **product/** (3 entries) — PRD craft, PRD innovation, gap analysis
-- **review/** (13 entries) — review methodology (shared), plus domain-specific review passes for PRD, user stories, domain modeling, ADRs, architecture, API design, database design, UX specification, testing, security, operations, implementation tasks
+- **core/** (26 entries) — eval craft, testing strategy, domain modeling, API design, database design, system architecture, ADR craft, security best practices, operations, task decomposition, user stories, UX specification, design system tokens, user story innovation, AI memory management, coding conventions, tech stack selection, project structure patterns, task tracking, CLAUDE.md patterns, multi-model review dispatch, review step template, dev environment, git workflow patterns, automated review tooling, vision craft
+- **product/** (5 entries) — PRD craft, PRD innovation, gap analysis, vision craft, vision innovation
+- **review/** (20 entries) — review methodology (shared), plus domain-specific review passes for PRD, user stories, domain modeling, ADRs, architecture, API design, database design, UX specification, testing, security, operations, implementation tasks, game design, game economy, game UI, netcode, and more
 - **validation/** (7 entries) — critical path analysis, cross-phase consistency, scope management, traceability, implementability, decision completeness, dependency validation
 - **finalization/** (3 entries) — implementation playbook, developer onboarding, apply-fixes-and-freeze
 - **execution/** (4 entries) — TDD execution loop, task claiming strategy, worktree management, enhancement workflow
-- **tools/** (3 entries) — release management, version strategy, session analysis
+- **tools/** (4 entries) — release management, version strategy, session analysis, and more
+- **game/** (24 entries) — game engines, networking/netcode, audio middleware, save systems, input patterns, VR/AR, localization, modding/UGC, live operations, platform certification, economy design, AI/behavior, level design, performance, accessibility
+- **web-app/** (17 entries) — rendering strategies (SSR/SSG/SPA), state management, authentication, deploy targets, real-time patterns, PWA, performance, security, testing, session patterns, UX patterns, caching, API integration, accessibility
+- **backend/** (14 entries) — API design patterns, data store selection, authentication mechanisms, messaging/event systems, observability, deploy strategies, caching, rate limiting, error handling, database migrations, testing, security
+- **cli/** (10 entries) — argument parsing, config management, output formatting, distribution channels, testing patterns, error handling, plugin architecture, shell integration, structured output, interactive prompts
 
 Each pipeline step declares which knowledge entries it needs in its frontmatter. The assembly engine injects them automatically. Knowledge files with a `## Deep Guidance` section are optimized for the CLI — only the deep guidance content is loaded into the assembled prompt, skipping the summary to avoid redundancy with the prompt text.
 

package/content/knowledge/backend/backend-api-design.md

@@ -0,0 +1,103 @@
+---
+name: backend-api-design
+description: REST maturity levels, GraphQL schema-first design, gRPC protobuf conventions, tRPC router patterns, API versioning strategies, pagination, and filtering
+topics: [backend, api-design, rest, graphql, grpc, trpc, versioning, pagination]
+---
+
+API design is a long-lived contract. Every structural decision — URL shape, error format, pagination scheme, versioning strategy — is expensive to change after consumers depend on it. Design APIs from the consumer's perspective first. The best API is one where new developers can predict the shape of an endpoint they have never seen before, because every other endpoint follows the same patterns.
+
+## Summary
+
+REST, GraphQL, gRPC, and tRPC each solve different problems. REST (Level 2 Richardson Maturity) is the default for most public APIs — use HTTP verbs correctly, plural nouns for collections, and nested paths for containment. GraphQL suits complex, multi-entity queries with schema-first design. gRPC is the standard for high-performance internal service-to-service calls. tRPC provides end-to-end type safety for TypeScript monorepos.
+
+API versioning, pagination, and filtering are long-lived contracts. URL path versioning is preferred for public APIs. Cursor-based pagination is the correct choice for any list that may grow large. All filter parameters must be validated against a schema before reaching the data layer.
+
+## Deep Guidance
+
+### REST Maturity Levels (Richardson Model)
+
+The Richardson Maturity Model is a pragmatic rubric, not a goal to maximize:
+
+- **Level 0**: Single endpoint, all operations via POST. Avoid — not REST.
+- **Level 1**: Separate resources at different URLs. Basic REST. Sufficient for many internal APIs.
+- **Level 2**: HTTP verbs used correctly (GET reads, POST creates, PUT/PATCH updates, DELETE removes). Standard REST. The target for most APIs.
+- **Level 3 (HATEOAS)**: Responses include hypermedia links describing available actions. Rarely justified in practice — adds response payload complexity and client coupling to URL structure. Only implement if clients genuinely traverse links without prior URL knowledge.
+
+Target Level 2 for REST APIs. Do not chase Level 3 as an ideological goal.
+
+**REST URL conventions**: Use plural nouns for collections (`/orders`), singular for specific resources (`/orders/{id}`), nested paths for containment (`/orders/{id}/items`), and action-oriented sub-resources for operations (`/orders/{id}/cancel`). Avoid verbs in URL paths.
+
+### GraphQL Schema-First Design
+
+Write the schema before writing resolvers. The schema is the API contract:
+
+- **Schema-first**: Define types, queries, mutations, and subscriptions in the SDL (Schema Definition Language) before any implementation. Generate types and resolver stubs from the schema.
+- **Single responsibility**: Each resolver does one thing. Business logic belongs in a service layer called by the resolver, not inside the resolver function.
+- **N+1 problem**: Every GraphQL API must address the N+1 query problem. Use DataLoader to batch and deduplicate database calls per request. An un-addressed N+1 in production is a performance crisis at scale.
+- **Pagination**: Use cursor-based pagination (Relay Connection spec) for any collection that may exceed 100 items. Offset pagination degrades at scale and produces incorrect results under concurrent inserts/deletes.
+- **Schema directives**: Use directives for cross-cutting concerns — `@auth`, `@deprecated`, `@rateLimit` — rather than duplicating logic in each resolver.
+
+### gRPC and Protobuf Conventions
+
+gRPC is the standard for high-performance internal service-to-service communication:
+
+- **Protobuf schema-first**: Define `.proto` files before any implementation. Store them in a shared repository or a dedicated `proto/` directory. Generate client and server stubs from the proto at build time.
+- **Naming**: Service names in `PascalCase`, RPC methods in `PascalCase`, message fields in `snake_case`. Follow the official Google API style guide for proto naming.
+- **Field numbering**: Never reuse a field number once it has been in production, even after the field is removed. Removing a field requires marking it `reserved`. Changing a field type is a breaking change.
+- **Streaming**: Use server-streaming for large result sets, bidirectional streaming for real-time updates, and unary calls for everything else. Don't over-use streaming — it complicates error handling and testing.
+
+### tRPC Router Patterns
+
+tRPC provides end-to-end type safety for TypeScript monorepos without a schema definition step:
+
+- **Procedure organization**: Group procedures into routers by domain (`appRouter.orders.create`, `appRouter.users.findById`). Each domain router lives in its own file.
+- **Input validation**: Every procedure must validate its input with a Zod schema. This is both a type contract and a runtime guard.
+- **Context**: Pass request-scoped data (authenticated user, database connection, logger) via the context object — never as procedure parameters.
+- **Middleware**: Apply authentication, rate limiting, and logging via tRPC middleware (`.use()`), not inside individual procedures.
+
+### API Versioning Strategies
+
+- **URL path versioning** (`/api/v1/`, `/api/v2/`): Most discoverable, easy to proxy and document. Preferred for public APIs. The version lives in the path, not just in headers.
+- **Header versioning** (`Accept: application/vnd.myapi.v2+json`): Cleaner URLs, harder to test in a browser. Preferred when URL cleanliness is a hard requirement.
+- **Query parameter** (`?v=2`): Easy to add but pollutes request URLs and caching keys.
+- **Sunset headers**: For deprecated versions, return `Sunset: Sat, 1 Jan 2025 00:00:00 GMT` and `Deprecation: true` headers on every response. Clients can detect imminent removal programmatically.
+
+### Pagination
+
+- **Cursor-based**: Use for any list that may grow large. Return a `cursor` (opaque string encoding the last item's sort key) in the response. The client passes `?after=<cursor>` for the next page. Stable under concurrent writes. Efficient at any offset depth.
+- **Offset-based** (`?page=3&limit=25`): Simple to implement. Acceptable for small, stable datasets. Degrades at large offsets (database must skip rows) and produces duplicates/gaps under concurrent mutations.
+- **Standard response envelope**: Every paginated list response should include `data: []`, `nextCursor` (or `nextPage`), and `total` (when computationally cheap).
+
+### Filtering and Sorting
+
+- Expose filtering via query parameters: `?status=active&createdAfter=2024-01-01`.
+- Expose sorting via `?sort=createdAt:desc` or `?sortBy=createdAt&order=desc`.
+- Validate all filter parameters against a schema before passing to the data layer. Never interpolate raw query parameters into SQL — use parameterized queries unconditionally.
+- Limit the surface area of filterable/sortable fields to those backed by indexes. Undocumented table scans at scale are a reliability incident.
+
+### Error Response Standards
+
+Standardize error responses across all API styles:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid request parameters",
+    "details": [
+      { "field": "email", "issue": "must be a valid email address" }
+    ],
+    "requestId": "req_abc123"
+  }
+}
+```
+
+Include a machine-readable `code` field that consumers can switch on without string-matching human-readable messages. Include the `requestId` in every error response to enable correlation with server-side logs.
+
+### API Design Review Checklist
+
+Before shipping any new endpoint: Does the URL follow the naming convention? Are all error responses structured with an error code? Is the success response envelope consistent with existing endpoints? Is pagination implemented for list endpoints? Are inputs validated with a schema? Is the endpoint documented in OpenAPI / GraphQL schema / proto? Are breaking changes versioned?
+
+### Rate Limiting Headers
+
+Every API should communicate rate limit state to callers via response headers. Include `X-RateLimit-Limit` (maximum requests per window), `X-RateLimit-Remaining` (requests left in current window), and `X-RateLimit-Reset` (UTC epoch seconds when the window resets). When the limit is exceeded, return `429 Too Many Requests` with a `Retry-After` header specifying seconds until the caller may retry. This enables well-behaved clients to self-throttle without guessing.

package/content/knowledge/backend/backend-architecture.md

@@ -0,0 +1,100 @@
+---
+name: backend-architecture
+description: Monolith vs microservices decision framework, layered architecture patterns, CQRS, event sourcing, hexagonal architecture, and service mesh considerations
+topics: [backend, architecture, microservices, monolith, cqrs, event-sourcing, hexagonal, clean-architecture]
+---
+
+Backend architecture is the set of structural decisions that determine how the system scales, how teams work independently, and how expensive future changes will be. The single most common backend architecture mistake is choosing microservices before the problem demands them. Start with the simplest architecture that solves the current problem, and evolve to complexity only when specific pain points — not hypothetical future ones — force the change.
+
+## Summary
+
+The single most common backend architecture mistake is choosing microservices before the problem demands them. Start with a monolith when the team is under 10-15 engineers or domain boundaries are unclear. Choose microservices only when parts of the system have genuinely different scaling requirements or teams need independent release cadences. The "modular monolith" is the underrated middle path.
+
+The foundational organizational pattern is layered architecture: controllers own HTTP, services own business logic, repositories own data access. Advanced patterns like CQRS, event sourcing, and hexagonal architecture solve specific problems and should not be adopted speculatively.
+
+## Deep Guidance
+
+### Monolith vs Microservices Decision Framework
+
+The choice is not philosophical — it is economic. Evaluate on these axes:
+
+**Choose a monolith when:**
+- Team size is under 10–15 engineers; coordination overhead of microservices exceeds the benefit
+- The domain boundaries are not yet clear; premature decomposition creates the wrong service boundaries that are expensive to undo
+- Operational maturity is low; microservices require observability, deployment pipelines, and network failure handling that monoliths do not
+- The project is new; a well-structured monolith can be extracted into services later, at a fraction of the cost of rebuilding distributed services into a monolith
+
+**Choose microservices when:**
+- Different parts of the system have genuinely different scaling requirements (image processing vs user authentication vs real-time chat)
+- Teams have hard ownership boundaries with independent release cadences; shared deployment is blocking velocity
+- Specific services need different technology choices (ML inference in Python, payment processing in Go, main app in Node.js)
+- The monolith's deployment coupling is causing real incidents — a change to a low-risk module blocking a high-stakes deployment
+
+The "modular monolith" is the underrated middle path: a single deployment with strong internal module boundaries, co-located services with strict import rules, and a clear extraction path to microservices when the time comes.
+
+### Layered Architecture (Controller → Service → Repository)
+
+The foundational pattern for backend organization separates concerns across three layers:
+
+- **Controller / Handler layer**: Owns HTTP. Parses requests, validates inputs, calls services, formats responses. Zero business logic.
+- **Service layer**: Owns business logic. Orchestrates domain operations. Depends on repository interfaces. Returns domain objects or throws domain errors. No knowledge of HTTP, SQL, or external API SDKs.
+- **Repository layer**: Owns data access. Translates between domain objects and persistence format. Exposes a domain-language interface: `findById`, `save`, `delete`.
+
+This separation enables unit testing services with mocked repositories — the most valuable test in the suite.
+
+### CQRS (Command Query Responsibility Segregation)
+
+CQRS separates read and write models. Commands mutate state; queries return state. This is not a default pattern — apply it when reads and writes have meaningfully different performance, consistency, or complexity requirements:
+
+- **Separate models**: The write model enforces invariants and emits events. The read model is denormalized for query performance — often a materialized view or a read-optimized document.
+- **When to use**: High-read / low-write ratios where the read query complexity is a bottleneck, systems where read and write consistency requirements differ, event-driven systems where the write side already produces events.
+- **When NOT to use**: Simple CRUD with no complex business rules; small teams where the dual-model overhead is not justified.
+
+### Event Sourcing
+
+Event sourcing stores the full history of state changes as an immutable event log, deriving current state by replaying events. This is a specialized pattern for specific use cases:
+
+- **When justified**: Audit trails are a hard requirement (financial transactions, medical records), temporal queries ("what was the account balance at 3pm Tuesday?"), complex event-driven workflows where the event history has business value.
+- **Cost**: Event replay infrastructure, eventual consistency complexity, developer mental overhead. Do not adopt speculatively.
+
+### Hexagonal / Clean Architecture
+
+Hexagonal architecture (Ports and Adapters) places the domain model at the center, surrounded by ports (interfaces) that define how the domain interacts with the outside world, and adapters that implement those interfaces for specific technologies:
+
+- **Core domain**: Pure business logic with no framework or infrastructure dependencies.
+- **Ports**: Interfaces the core defines. `UserRepository` is a port; `PostgresUserRepository` is an adapter.
+- **Adapters**: HTTP controllers, database repositories, message queue consumers, external API clients.
+
+The benefit: the domain is testable in isolation from all infrastructure. The cost: more interfaces and indirection. Apply when the domain is complex and long-lived; overkill for simple CRUD services.
+
+### Service Mesh Considerations
+
+Service meshes (Istio, Linkerd, Consul Connect) add a sidecar proxy to each service pod, providing mTLS, traffic management, circuit breaking, and observability without application code changes. Consider only when:
+
+- You have 10+ microservices and the operational complexity of per-service networking configuration is unsustainable
+- Zero-trust networking is a compliance requirement
+- You need traffic splitting for canary deployments at the infrastructure level
+
+A service mesh adds significant operational overhead. Validate the need against simpler alternatives (application-level circuit breakers with Resilience4j / Polly / opossum, API gateway traffic management) before committing.
+
+### Modular Monolith Implementation
+
+A modular monolith combines the deployment simplicity of a monolith with the code isolation of microservices:
+
+- **Module boundaries**: Each module has its own directory with a public API (exported functions/types) and private internals. Modules communicate through well-defined interfaces, not direct imports of internal implementation.
+- **Enforce boundaries**: Use ESLint import rules, TypeScript project references, or build-time checks to prevent cross-module imports that bypass the public API. The rule: Module A may import from Module B's public API but never from its internal implementation files.
+- **Database isolation**: Each module owns its tables and never queries another module's tables directly. Cross-module data access goes through the module's service interface. This discipline makes future extraction to microservices possible without rewriting the data layer.
+- **Shared kernel**: A small shared layer provides cross-cutting concerns (auth, logging, error types) used by all modules. Keep the shared kernel minimal — every shared type is a coupling point.
+
+The modular monolith is the underrated default architecture for teams of 5–15 engineers. It avoids the operational overhead of microservices while providing the code isolation that prevents monolith rot.
+
+### API Gateway Pattern
+
+An API gateway sits in front of backend services and provides a unified entry point:
+
+- **Routing**: Route requests to the appropriate service based on URL path or header
+- **Cross-cutting concerns**: Authentication, rate limiting, request logging, and CORS handled once at the gateway rather than duplicated in each service
+- **Response aggregation**: Combine responses from multiple services into a single response for the client (BFF-like behavior)
+- **Tools**: Kong, AWS API Gateway, Traefik, Envoy, or a custom Express/Fastify proxy
+
+Use an API gateway when you have 3+ services that share auth and rate limiting requirements. Do not use one for a single service — the added hop is pure overhead.

package/content/knowledge/backend/backend-async-patterns.md

@@ -0,0 +1,101 @@
+---
+name: backend-async-patterns
+description: Message queue patterns, event-driven architecture, saga patterns, retry strategies, and idempotency keys
+topics: [backend, async, message-queues, event-driven, saga, retry, idempotency, cqrs]
+---
+
+Asynchronous patterns decouple services in time and space, enabling systems to absorb load spikes, survive partial failures, and scale independently — but they introduce delivery guarantees and consistency tradeoffs that must be designed for explicitly from the start.
+
+## Summary
+
+Asynchronous patterns come in two primary shapes: pub/sub for fan-out scenarios and work queues for competing consumers. Dead letter queues capture messages that exhaust retry attempts. Always configure a DLQ — without one, unprocessable messages either loop forever or are silently lost.
+
+For distributed transactions, the saga pattern coordinates multi-step operations across services using either choreography (event-driven) or orchestration (central coordinator). All retry strategies should use exponential backoff with jitter to prevent retry storms, and circuit breakers prevent cascading failures when downstream services are degraded.
+
+## Deep Guidance
+
+### Message Queue Patterns
+
+**Pub/sub (publish-subscribe):** Publishers emit events to a topic without knowing who consumes them. Multiple subscribers independently receive each message. Use for fan-out scenarios — an order placed event triggers inventory update, email notification, and analytics simultaneously.
+
+**Work queues (competing consumers):** Messages are distributed across multiple workers; each message is processed by exactly one worker. Use for task distribution — image processing, email sending, PDF generation. Enables horizontal scaling: add workers to increase throughput.
+
+**Dead letter queues (DLQ):** Messages that fail after the maximum retry attempts are moved to a DLQ instead of being dropped. Monitor DLQ depth as a health signal. Inspect failed messages, fix the root cause, then replay from the DLQ. Always configure a DLQ — without one, unprocessable messages either loop forever or are silently lost.
+
+### Event-Driven Architecture
+
+**Event sourcing:** Store the sequence of state-changing events as the system of record, not the current state. The current state is a projection derived by replaying events. Benefits: complete audit history, ability to reconstruct past state, event replay for debugging. Cost: more complex reads (projections), eventual consistency, snapshot management for performance.
+
+**CQRS (Command Query Responsibility Segregation):** Separate the write model (commands that change state) from the read model (queries optimized for display). Commands go through validation and business logic; read models are denormalized for query performance. Event sourcing and CQRS are often paired but are independent patterns — CQRS is valuable without event sourcing when read and write workloads have very different shapes.
+
+**Event schema evolution:** Version event schemas from the start. Consumers must handle older event versions gracefully. Use a schema registry (Confluent Schema Registry, AWS Glue Schema Registry) to enforce compatibility. Prefer additive changes (new optional fields) over breaking changes.
+
+### Saga Pattern for Distributed Transactions
+
+Sagas coordinate multi-step transactions across services without two-phase commit. Each step has a compensating transaction that undoes its effect.
+
+**Choreography:** Each service emits events and other services react. No central coordinator. Simpler but harder to trace and reason about for long workflows.
+
+**Orchestration:** A saga orchestrator service drives the workflow, calling each participant and issuing compensating calls on failure. Easier to trace and monitor; the orchestrator is a single point of failure.
+
+Use sagas when: a business operation spans multiple services or databases, and full ACID transactions are not available. Always design compensating transactions before implementing the forward path.
+
+### Retry Strategies
+
+**Exponential backoff:** After a failure, wait before retrying. Double the wait on each subsequent attempt: 1s, 2s, 4s, 8s, 16s. Add jitter (randomness of ±25%) to prevent retry storms — without jitter, all callers retry simultaneously and overwhelm the recovering service.
+
+**Maximum attempts:** Cap total retries (typically 3–5). After the maximum, either raise the error to the caller, move the message to a DLQ, or trigger an alert.
+
+**Circuit breaker:** Track the failure rate of calls to a dependency. When failures exceed a threshold (e.g., 50% of calls in the last 10 seconds), open the circuit and immediately return an error without attempting the call. After a cooldown period, allow a single probe request — if it succeeds, close the circuit; if it fails, stay open. Circuit breakers prevent cascading failures when a downstream service is slow or down.
+
+### Idempotency Keys
+
+Make all mutating operations idempotent so they can be safely retried. The client generates a unique idempotency key (UUID) and sends it with the request. The server records the key and the response. On a duplicate request with the same key, return the stored response without re-executing the operation.
+
+**Storage:** Store idempotency keys in Redis or the database with the operation result. Set TTL based on reasonable retry windows (24 hours for payments, 1 hour for most operations).
+
+**Scope:** Idempotency keys must be scoped to a user or API key — global keys are a DoS vector. Return `409 Conflict` if the same key is used with different request parameters (key collision detection).
+
+Design database operations to be naturally idempotent where possible: `INSERT ... ON CONFLICT DO NOTHING`, `UPSERT`, or check-then-insert in a transaction.
+
+### Message Ordering Guarantees
+
+Different messaging systems provide different ordering guarantees:
+
+- **FIFO (First In, First Out)**: SQS FIFO queues, Kafka partitions. Messages are delivered in the order they were sent. Useful for operations where order matters (sequential state transitions, financial transactions).
+- **Best-effort ordering**: Standard SQS, most pub/sub systems. Messages may arrive out of order. Design consumers to handle reordering — use sequence numbers or timestamps to detect and resolve ordering conflicts.
+- **Partition-level ordering**: Kafka guarantees order within a partition. Use a partition key (user ID, order ID) to ensure all related messages go to the same partition and are processed in order.
+
+When order matters, choose a system that guarantees it at the partition level rather than trying to enforce ordering at the application level. Application-level ordering (hold messages in a buffer, sort, then process) is fragile and adds latency.
+
+### Backpressure Strategies
+
+When a producer emits messages faster than consumers can process them, the system needs a backpressure strategy:
+
+- **Queue depth limits**: Set a maximum queue depth. When the queue is full, the producer receives an error and must retry or drop the message. This prevents unbounded memory growth.
+- **Rate limiting at the producer**: Throttle the producer based on consumer throughput. The producer monitors queue depth and reduces its emit rate when the queue approaches capacity.
+- **Consumer scaling**: Automatically scale consumer instances based on queue depth. When depth exceeds a threshold, add workers. When it drops, scale down. Cloud-native options: AWS Lambda with SQS triggers (auto-scales), Kubernetes KEDA (queue-based autoscaler).
+- **Shedding**: When overwhelmed, intentionally drop low-priority messages rather than processing everything slowly. Useful for telemetry or analytics events where some data loss is acceptable.
+
+Monitor queue depth and consumer lag as primary health indicators. A growing queue depth means consumers are falling behind — this is a capacity planning signal, not a bug to ignore.
+
+### Transactional Outbox Pattern
+
+The transactional outbox pattern ensures that database writes and message publishing are atomic — either both happen or neither does:
+
+1. Write the business data and the outbox event to the database in the same transaction
+2. A separate process (poller or CDC) reads the outbox table and publishes events to the message queue
+3. Mark outbox entries as published after successful delivery
+
+This eliminates the dual-write problem where the database commit succeeds but the message publish fails (or vice versa). Use database CDC (Change Data Capture) with Debezium for production-grade implementations.
+
+### Choosing a Message Broker
+
+Select the broker based on throughput, ordering, and operational requirements:
+
+- **Redis (via BullMQ, Redis Streams)**: Good for moderate throughput, simple to operate, already present in most stacks. Limited durability if Redis is not configured with AOF persistence. Best for job queues and task distribution.
+- **RabbitMQ**: Full-featured broker with routing, exchanges, and consumer acknowledgment. Excellent for complex routing topologies. More operational overhead than Redis.
+- **Kafka**: Designed for high-throughput event streaming with durable, ordered, replayable logs. Best for event-driven architectures where consumers need to replay history. Highest operational overhead.
+- **SQS / Cloud Pub/Sub**: Managed services with zero operational overhead. Limited features compared to self-hosted brokers but eliminate infrastructure management entirely. Default choice for cloud-native services unless a specific feature gap forces self-hosting.
+
+Start with the simplest broker that meets the requirements. Migrating from Redis to Kafka later is straightforward if the consumer interface is abstracted behind a repository pattern.

package/content/knowledge/backend/backend-auth-patterns.md

@@ -0,0 +1,100 @@
+---
+name: backend-auth-patterns
+description: JWT lifecycle, OAuth2 authorization code flow, API key management, and service-to-service authentication
+topics: [backend, auth, jwt, oauth2, api-keys, mtls, security]
+---
+
+Authentication and authorization are the first line of defense for any backend service — mistakes here compromise the entire system, making it essential to use proven patterns like JWTs with rotation, OAuth2 with PKCE, and workload identity from the start.
+
+## Summary
+
+Authentication and authorization patterns for backend services center on three areas: JWTs with short expiry and refresh-token rotation for user sessions, OAuth2 authorization code flow with PKCE for third-party integrations, and scoped API keys with hashed storage for programmatic access. Service-to-service authentication uses mTLS, HMAC request signing, or cloud workload identity.
+
+Every auth mechanism requires explicit key rotation, revocation procedures, and scope enforcement. Never put sensitive data in JWT payloads and never store API keys unhashed.
+
+## Deep Guidance
+
+### JWT Lifecycle
+
+Issue JWTs with short expiry (15–60 minutes) signed with RS256 or ES256. Include only the minimum claims needed: `sub`, `iat`, `exp`, `iss`, `aud`, and application-specific role or scope claims. Never put sensitive data in the payload — it is base64-encoded, not encrypted.
+
+**Refresh flow:** Issue a long-lived refresh token (7–30 days) stored in an HttpOnly, Secure, SameSite=Strict cookie. On access-token expiry the client posts to `/auth/refresh`; the server validates the refresh token, issues a new access token, and optionally rotates the refresh token (sliding expiry). Implement refresh-token rotation to detect token theft: if an already-used refresh token is presented, revoke the entire family and force re-login.
+
+**Revocation:** JWTs are stateless by design — revocation requires a blocklist. Store revoked token JTIs in Redis with TTL matching the token's remaining lifetime. Check the blocklist on every request only for high-security operations; skip the check for low-risk reads when performance matters and accept the short window of continued validity.
+
+**Key rotation:** Support multiple active signing keys identified by `kid` header. Add the new key to the JWKS endpoint, start signing with it, keep the old key for validation until all tokens signed with it have expired, then remove it.
+
+### OAuth2 Authorization Code Flow
+
+Use the authorization code flow (with PKCE) for any user-facing OAuth2 integration — never implicit or client credentials on the frontend.
+
+1. Generate a cryptographically random `state` parameter and PKCE `code_verifier`/`code_challenge`. Store both in the session.
+2. Redirect the user to the provider's authorization endpoint with `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`, and `code_challenge`.
+3. On callback, verify `state` matches the session value (CSRF protection), then exchange `code` + `code_verifier` for tokens via a server-side POST.
+4. Store the provider's access token server-side (never expose it to the browser). Use it to fetch the user's profile and map to a local user record.
+5. Issue your own session or JWT — do not use the provider's token as your application's auth token.
+
+### API Key Management
+
+**Generation:** Use cryptographically random 32-byte values encoded as hex or base58. Prefix keys with a service identifier (`sk_live_`, `pk_test_`) for easy identification in logs and leaked-credential scanners.
+
+**Storage:** Hash the key (SHA-256) before storing in the database, just like a password. Only show the full key once at creation time. Store metadata alongside the hash: name, scopes, last-used timestamp, expiry, owner.
+
+**Scoping:** Define fine-grained scopes (`orders:read`, `webhooks:write`) and require callers to request minimum necessary scopes. Validate scope on each request against the endpoint's required permissions.
+
+**Rotation:** Provide a rotation endpoint that issues a new key and returns both old and new simultaneously. Set a grace period (e.g., 24 hours) during which both keys are valid, then revoke the old key. Send email/webhook notifications before expiry.
+
+### Service-to-Service Authentication
+
+**mTLS:** Both client and server present TLS certificates. The server verifies the client certificate against a trusted CA. Use a private CA (cert-manager on Kubernetes, AWS Private CA) to issue short-lived service certificates. Rotate certificates automatically before expiry. mTLS is the strongest service-to-service option and integrates with service meshes (Istio, Linkerd).
+
+**Shared secrets / HMAC request signing:** For simpler setups, sign requests with an HMAC-SHA256 of the canonical request (method + path + timestamp + body hash) using a shared secret. Include the signature and timestamp in a request header. The receiving service verifies the signature and rejects requests with timestamps older than 5 minutes (replay protection). Rotate shared secrets via a dual-key window.
+
+**Workload identity:** On cloud platforms, prefer workload identity (AWS IAM roles for service accounts, GCP Workload Identity Federation) over static shared secrets. Credentials are issued dynamically by the platform and rotate automatically.
+
+### Session Management Patterns
+
+For server-rendered applications or APIs that need session state:
+
+- **Server-side sessions**: Store session data in Redis or a database. The client holds only an opaque session ID in an HttpOnly, Secure, SameSite=Strict cookie. Server looks up the session on each request. Benefits: easy revocation, no client-side state management. Cost: every request hits the session store.
+- **Stateless JWT sessions**: The JWT itself is the session. Benefits: no session store, horizontal scaling without shared state. Cost: revocation requires a blocklist, token size grows with claims, tokens cannot be invalidated before expiry without extra infrastructure.
+- **Hybrid approach**: Use JWTs for short-lived access (15 minutes) and server-side sessions for refresh tokens. This provides the performance benefits of stateless access tokens with the revocability of server-side sessions.
+
+Choose server-side sessions for applications with strict revocation requirements (banking, healthcare). Choose stateless JWTs for high-throughput APIs where the operational overhead of a session store is not justified.
+
+### Permission Models
+
+Authorization beyond authentication requires an explicit permission model:
+
+- **RBAC (Role-Based Access Control)**: Users are assigned roles (admin, editor, viewer). Roles map to permissions. Simple to implement, hard to evolve when permission granularity requirements grow. Suitable for most applications with fewer than 20 distinct permission levels.
+- **ABAC (Attribute-Based Access Control)**: Permissions evaluated based on user attributes, resource attributes, and environmental context. More flexible than RBAC but more complex to implement and audit. Use when the same user needs different permissions on different resources based on attributes (department, project membership, data sensitivity).
+- **ReBAC (Relationship-Based Access Control)**: Permissions derived from the relationship between users and resources (ownership, team membership, sharing). Google Zanzibar model. Implemented by OpenFGA, SpiceDB, Ory Keto. Use for applications with complex sharing and collaboration features (Google Docs-style permissions).
+
+Regardless of model, enforce authorization at the service layer — not at the controller level. A controller that checks permissions directly is duplicating security logic that should be centralized.
+
+### Token Storage Best Practices
+
+Where tokens are stored determines the attack surface:
+
+- **HttpOnly cookies**: Protected from XSS (JavaScript cannot read them). Vulnerable to CSRF without SameSite and CSRF tokens. The recommended storage for refresh tokens.
+- **Authorization header (Bearer token)**: Tokens stored in memory. Lost on page refresh. Not vulnerable to CSRF. Suitable for SPAs where the token is fetched from a server-side session on load.
+- **localStorage**: Persistent across sessions but fully accessible to any JavaScript on the page. Never store refresh tokens or long-lived credentials in localStorage — a single XSS vulnerability compromises them.
+
+### CSRF Protection
+
+Cross-Site Request Forgery (CSRF) attacks trick authenticated browsers into making unintended requests. Protection strategies:
+
+- **SameSite cookies**: Set `SameSite=Strict` or `SameSite=Lax` on session cookies. `Strict` prevents the cookie from being sent on any cross-site request, including navigation. `Lax` allows the cookie on top-level GET navigations (safe for most cases).
+- **Double-submit cookie**: Generate a random CSRF token, set it as a cookie, and require the client to include it in a custom header (`X-CSRF-Token`). The server verifies the header matches the cookie. Attackers cannot read cross-origin cookies to include the header.
+- **Origin header validation**: Check the `Origin` or `Referer` header on state-changing requests. Reject requests from unknown origins. This is a defense-in-depth measure, not a standalone protection.
+- **Token-per-request**: For highest security, generate a unique CSRF token per form render and validate it on submission. More complex but eliminates token reuse attacks.
+
+When using JWT bearer tokens in Authorization headers (not cookies), CSRF protection is not needed — the token is not sent automatically by the browser.
+
+### Multi-Factor Authentication Integration
+
+For applications requiring MFA:
+
+- **TOTP (Time-based One-Time Password)**: Standard algorithm (RFC 6238) compatible with Google Authenticator, Authy, 1Password. Generate a secret key, encode as a QR code URI, and verify the 6-digit code during login. Store the secret key encrypted in the database.
+- **WebAuthn / Passkeys**: Hardware key or biometric authentication via the Web Authentication API. Strongest option — phishing-resistant. Support as the primary MFA method for security-sensitive applications.
+- **Recovery codes**: Generate 8-10 single-use recovery codes during MFA enrollment. Hash them like passwords. Display only once at enrollment. These are the escape hatch when the user loses their MFA device.