@zigrivers/scaffold 3.6.0 → 3.8.0

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

@@ -0,0 +1,105 @@
+---
+name: backend-conventions
+description: Service and handler naming conventions, structured error handling patterns, structured logging with correlation IDs, and file organization standards for backend codebases
+topics: [backend, conventions, error-handling, logging, naming, file-organization]
+---
+
+Consistent conventions in a backend codebase reduce cognitive load, make code reviewable at a glance, and prevent entire classes of bugs. Naming, error handling, and logging are the three highest-leverage areas — they touch every layer of the stack and every engineer on the team. Establish these conventions before the first PR, codify them in linting rules where possible, and treat violations as blocking review comments.
+
+## Summary
+
+Backend conventions cover naming, error handling, logging, and file organization. Services are named after domain concepts (noun form), handlers after HTTP resources, and repositories after data entities. Structured errors use machine-readable codes; structured logs emit JSON with correlation IDs. Group by layer in small services, by feature/domain in large codebases.
+
+Conventions enforced only by humans drift immediately. Automate with ESLint, TypeScript strict mode, commit hooks, and schema validation in integration tests.
+
+## Deep Guidance
+
+### Service and Handler Naming
+
+Names should reveal intent and be consistent across the codebase:
+
+- **Services**: Named after the domain concept they own, noun form. `OrderService`, `UserAuthService`, `PaymentProcessor`. One service per domain concept. Services contain business logic only — no HTTP, no database drivers.
+- **Handlers / Controllers**: Named after the HTTP resource or operation. `OrdersHandler`, `UserController`, `AuthRouter`. One handler per resource family. Handlers translate HTTP concerns to service calls — no business logic.
+- **Repository / DAO classes**: `OrderRepository`, `UserStore`. Contain only data-access logic. No business rules, no HTTP.
+- **Method naming**: Use verb-noun patterns that reveal intent. Prefer `createOrder`, `cancelOrder`, `findOrdersByCustomer` over generic `get`, `set`, `update`. Reserve `get` for trivial accessors.
+- **File names**: Match the class/module name in kebab-case. `order-service.ts`, `orders-handler.ts`, `order-repository.ts`.
+
+### Structured Error Handling
+
+Unstructured errors (`throw new Error("something went wrong")`) are a maintenance liability. Use structured errors throughout:
+
+- **Error codes**: Define an enum or constant map of machine-readable error codes. `ORDER_NOT_FOUND`, `PAYMENT_DECLINED`, `INSUFFICIENT_INVENTORY`. Codes enable consumers to handle specific failure cases without string parsing.
+- **Error shape**: Standardize the error response object across all endpoints. A minimal shape: `{ code: string, message: string, details?: unknown, requestId: string }`. Never leak stack traces to API consumers in production.
+- **Error categories**: Separate operational errors (expected, business logic failures) from programmer errors (unexpected, indicative of a bug). Operational errors are `4xx`; programmer errors are `5xx`. Log programmer errors with full context.
+- **Never swallow errors**: A bare `catch {}` or `catch (e) { /* ignore */ }` is a production bug waiting to surface. At minimum, log the error with context. If the error is expected and recoverable, handle it explicitly and document why.
+
+### Structured Logging
+
+Log entries are your primary debugging tool in production. Treat them as a first-class API:
+
+- **Structured format**: Always emit JSON logs. Human-readable log lines are unsearchable at scale. Every entry should be a JSON object parseable by log aggregation tools (Datadog, Loki, CloudWatch).
+- **Required fields on every log entry**: `timestamp` (ISO 8601), `level` (debug/info/warn/error), `message`, `service`, `requestId` (correlation ID), `environment`.
+- **Correlation IDs**: Generate a `requestId` (UUID v4) at the API gateway or first handler and propagate it through every downstream service call via a header (`X-Request-ID`) and a context object (AsyncLocalStorage in Node.js). Every log line and error response includes this ID. A support ticket becomes: "give me requestId X" → full trace in 10 seconds.
+- **Log levels**: `debug` — internal state, loop iterations (disabled in production); `info` — request start/end, state transitions; `warn` — recoverable anomalies, deprecated usage; `error` — failures requiring human attention.
+- **Avoid over-logging**: Logging every field of every object in a high-throughput path fills disks and incurs cost. Log decision points, not data dumps.
+
+### File Organization
+
+Enforce a predictable directory layout:
+
+- Group by layer, not by feature, in small services. In larger codebases, group by feature/domain with layer sub-directories.
+- Test files co-located with source files (`order-service.test.ts` next to `order-service.ts`) or in a parallel `__tests__/` directory — choose one pattern and enforce it.
+- Configuration files at the root of `src/`, not scattered across subdirectories.
+
+### Enforcing Conventions with Tooling
+
+Conventions enforced by humans alone drift. Use automated tools:
+
+- **ESLint / Biome**: Enforce naming patterns, ban `console.log` in favor of a logger, require explicit error handling.
+- **TypeScript strict mode**: Catches the class of errors that naming conventions alone cannot prevent — `strictNullChecks`, `noImplicitAny`, `noUncheckedIndexedAccess`.
+- **Commit hooks**: Run linting on staged files via `lint-staged` + `husky`. Prevents convention drift from reaching the repository.
+- **OpenAPI response schema validation**: Validate that error responses match the standard shape in integration tests. Catches endpoints that return non-standard errors before they reach production.
+
+### Naming Conventions by Language
+
+Each language ecosystem has established naming conventions. Follow them without exception:
+
+**TypeScript/Node.js:**
+- Files: `kebab-case.ts` (`order-service.ts`, `payment-handler.ts`)
+- Classes: `PascalCase` (`OrderService`, `PaymentHandler`)
+- Functions/methods: `camelCase` (`createOrder`, `findUserById`)
+- Constants: `UPPER_SNAKE_CASE` (`MAX_RETRIES`, `DEFAULT_TIMEOUT_MS`)
+- Interfaces/Types: `PascalCase` with no prefix (`OrderData`, not `IOrderData`)
+
+**Python:**
+- Files: `snake_case.py` (`order_service.py`)
+- Classes: `PascalCase` (`OrderService`)
+- Functions/methods: `snake_case` (`create_order`, `find_user_by_id`)
+- Constants: `UPPER_SNAKE_CASE` (`MAX_RETRIES`)
+
+**Go:**
+- Files: `snake_case.go` (`order_service.go`)
+- Exported: `PascalCase` (`CreateOrder`)
+- Unexported: `camelCase` (`validateInput`)
+- Packages: lowercase, single word (`orders`, not `orderService`)
+
+### Request/Response Envelope Standards
+
+Standardize the shape of all API responses:
+
+```json
+{
+  "data": { "id": "ord_123", "status": "created" },
+  "meta": { "requestId": "req_abc", "timestamp": "2024-01-15T10:30:00Z" }
+}
+```
+
+For error responses:
+```json
+{
+  "error": { "code": "NOT_FOUND", "message": "Order not found", "details": [] },
+  "meta": { "requestId": "req_abc", "timestamp": "2024-01-15T10:30:00Z" }
+}
+```
+
+Never mix success and error shapes. A response has either `data` or `error`, never both. This makes client-side type discrimination trivial. Include `meta` on every response for debugging and correlation.

package/content/knowledge/backend/backend-data-modeling.md

@@ -0,0 +1,102 @@
+---
+name: backend-data-modeling
+description: Relational vs document modeling tradeoffs, migration strategies, connection pooling, ORM vs query builder tradeoffs, multi-tenancy patterns, and eventual consistency
+topics: [backend, data-modeling, database, migrations, orm, multi-tenancy, eventual-consistency, connection-pooling]
+---
+
+Data modeling decisions have the highest reversal cost of any backend choice. A schema design that seemed reasonable at launch can become an operational crisis at scale — queries that worked at 10,000 rows fail at 100 million. The goal is to match the data model to the access patterns of the application, not to normalize for its own sake or to denormalize prematurely. Design the schema with the queries in mind from day one.
+
+## Summary
+
+Data modeling decisions have the highest reversal cost of any backend choice. Choose relational databases for transactional integrity and complex queries, document stores for hierarchical data read as a unit. Use versioned migrations for all schema changes with non-destructive patterns for zero-downtime deploys. Every production backend requires connection pooling; pool exhaustion under load is a complete outage.
+
+Multi-tenancy, eventual consistency, and ORM vs query builder selection are load-bearing choices that must be made with explicit tradeoff acknowledgment before the first schema ships.
+
+## Deep Guidance
+
+### Relational vs Document Modeling
+
+Choose based on your access patterns and data structure, not familiarity:
+
+**Relational (PostgreSQL, MySQL):**
+- Strong fit for: highly relational data with many join paths, transactional integrity across multiple entities (financial records, inventory), complex queries with ad hoc filter combinations, strict schema enforcement.
+- Use normalized forms (3NF) as the default. Denormalize only for specific, measured performance bottlenecks, not speculatively.
+- PostgreSQL's JSONB column type gives you document storage inside a relational database — defer the choice of full document store until the access pattern clearly demands it.
+
+**Document (MongoDB, DynamoDB, Firestore):**
+- Strong fit for: hierarchical or nested data read as a unit (a blog post with all its comments), schema-less or rapidly evolving schemas, single-entity lookups by a known ID, extreme write throughput.
+- Weak fit for: ad hoc querying across multiple attributes, transactions spanning multiple documents, highly relational data with many access patterns.
+- The most common document modeling mistake is replicating relational joins via application-level fetching — this is an N+1 at the data layer and scales poorly.
+
+### Migration Strategies
+
+Every schema change must go through a versioned migration:
+
+- **Non-destructive first**: Add new columns as nullable or with defaults. Only make existing columns NOT NULL after backfilling all rows. This enables zero-downtime deployments where the old and new app versions run simultaneously.
+- **Expand-contract pattern**: For large schema changes — (1) expand: add new column/table while keeping old; (2) backfill data; (3) deploy code that writes to both; (4) contract: remove old column/table once all consumers use the new one.
+- **Irreversible migrations**: Some changes cannot be undone (dropping a column, deleting data). Flag these explicitly in code and in your migration changelog. Require explicit human sign-off before running in production.
+- **Test migrations against production data size**: A migration that runs in 2 ms on 1,000 rows may lock a table for 20 minutes on 100 million rows. Use `pt-online-schema-change` (MySQL) or `pg_repack` / `CREATE INDEX CONCURRENTLY` (PostgreSQL) for zero-lock migrations on large tables.
+
+### Connection Pooling
+
+Every production backend must use a connection pool. Direct connections to the database at high concurrency exhaust database connection limits within minutes:
+
+- **Application-level pooling**: PgBouncer (PostgreSQL), ProxySQL (MySQL), or the ORM's built-in pool (Prisma, Sequelize, Knex). Configure `min`, `max`, and `idleTimeoutMillis`.
+- **Right-sizing the pool**: A pool larger than the database can handle is worse than no pool. PostgreSQL supports ~100 active connections by default before performance degrades. Rule of thumb: pool size = (number of CPU cores × 2) + effective spindle count.
+- **Monitor pool saturation**: Alert when `waiting_clients` exceeds zero for more than a few seconds. Pool exhaustion under load is a complete service outage.
+
+### ORM vs Query Builder
+
+| | ORM (Prisma, TypeORM, Hibernate) | Query Builder (Knex, JOOQ, Drizzle) |
+|---|---|---|
+| Productivity | Higher for standard CRUD | Higher for complex SQL |
+| Complex queries | Awkward, often forces raw SQL | Natural SQL expression |
+| Type safety | High (Prisma) to medium | Medium to high (Drizzle) |
+| Performance | Can hide N+1s | Explicit, predictable |
+| Migration | Built-in (Prisma) | Manual or separate tool |
+
+Use an ORM for standard CRUD-heavy domains. Use a query builder or raw SQL for analytics, reporting, or any service where query control is critical. Do not mix ORMs in the same service — pick one.
+
+### Multi-Tenancy Patterns
+
+Three approaches, ordered by isolation strength:
+
+- **Shared schema / shared tables**: Row-level isolation via a `tenant_id` column. Simplest to operate; strongest risk of data leakage if a query omits the tenant filter. Always enforce tenant filtering via a middleware or database row-level security (PostgreSQL RLS).
+- **Shared database / separate schemas**: Each tenant gets their own schema. Better isolation, more complex migrations (must apply to all tenant schemas), good balance for B2B SaaS.
+- **Separate databases per tenant**: Full isolation. High operational overhead — connection pools multiply by tenant count. Justified for enterprise customers with contractual data isolation requirements.
+
+### Eventual Consistency
+
+Distributed systems and event-driven architectures introduce eventual consistency:
+
+- **Identify consistency requirements explicitly**: Which operations require immediate consistency (payment confirmation, inventory reservation) vs eventual (email notification, analytics event)? Document this per use case.
+- **Idempotency**: All event consumers and queue workers must be idempotent — processing the same message twice produces the same outcome as processing it once. Use an idempotency key stored in the database to detect duplicates.
+- **Sagas for distributed transactions**: When a business operation spans multiple services with no shared transaction, use the Saga pattern — a sequence of local transactions with compensating transactions for rollback. Choreography (event-driven) or orchestration (central coordinator) variants.
+
+### Index Strategy
+
+An unindexed query on a large table is a latency spike and a database lock. Index columns that appear in `WHERE`, `ORDER BY`, `GROUP BY`, and `JOIN ON` clauses. Over-indexing is also a problem — indexes slow writes. Review the query plan (`EXPLAIN ANALYZE`) for every significant query before shipping. Index maintenance is a recurring task, not a one-time setup.
+
+### Soft Deletes vs Hard Deletes
+
+- **Soft deletes**: Add a `deleted_at` timestamp column. Rows are never physically removed; queries filter with `WHERE deleted_at IS NULL`. Benefits: audit trail, easy recovery, referential integrity preserved. Cost: every query must include the filter (use a database view or ORM default scope to enforce this), storage grows indefinitely.
+- **Hard deletes**: Rows are physically removed with `DELETE`. Benefits: simpler queries, smaller tables, no filter overhead. Cost: data is gone, referential integrity may break if foreign keys exist.
+- **Archive pattern**: Move deleted rows to a separate `_archive` table in the same transaction. Active table stays clean; historical data is preserved. Best of both worlds at the cost of archive table maintenance.
+
+Default to soft deletes for business entities (users, orders, products). Use hard deletes for ephemeral data (sessions, temp tokens, analytics events past retention).
+
+### Data Retention and Purging
+
+Define retention policies explicitly for each table:
+
+- **Regulatory**: Financial records may require 7-year retention. Medical records vary by jurisdiction. Document the legal basis for each retention period.
+- **Operational**: Log tables, event tables, and session tables should have automated purging. Use database partitioning by date and drop old partitions — this is orders of magnitude faster than `DELETE WHERE created_at < ?`.
+- **Implementation**: Schedule a recurring job (cron, pg_cron, Kubernetes CronJob) that purges expired data. Alert if the job fails silently — unpurged data grows disk usage and degrades query performance over months.
+
+### Query Optimization Fundamentals
+
+Before optimizing, measure. Use `EXPLAIN ANALYZE` (PostgreSQL) or `EXPLAIN FORMAT=JSON` (MySQL) to understand the query plan:
+
+- **Sequential scans on large tables**: Add an index on the filtered column. A sequential scan on a million-row table that should be an index scan is the most common performance bug.
+- **Index-only scans**: When the query only needs columns in the index, the database reads the index without touching the table. Use covering indexes (`CREATE INDEX ... INCLUDE (col)`) for frequently queried column combinations.
+- **Join order**: The query planner usually picks the right join order, but with 5+ joins, it may choose poorly. Use `EXPLAIN` to verify. If the planner is wrong, consider rewriting as CTEs or materializing intermediate results.

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

@@ -0,0 +1,100 @@
+---
+name: backend-deployment
+description: Containerization best practices, serverless patterns, health check endpoints, graceful shutdown, and deployment strategies
+topics: [backend, deployment, docker, serverless, health-checks, graceful-shutdown, blue-green, canary]
+---
+
+Deployment reliability is a multiplier on every other engineering investment — a well-written service that deploys poorly will cause more incidents than a mediocre service that deploys safely and rolls back cleanly.
+
+## Summary
+
+Backend deployment covers containerization with multi-stage builds, serverless cold-start mitigation, health check endpoints, graceful shutdown, and deployment strategies. Every service needs liveness (`/health`) and readiness (`/ready`) endpoints. Handle `SIGTERM` for clean request draining during deploys.
+
+Use blue-green or canary deployment strategies for production to minimize downtime and catch regressions under real traffic. Always run containers as non-root users with read-only filesystems.
+
+## Deep Guidance
+
+### Containerization
+
+**Multi-stage Dockerfile:** Use separate build and runtime stages. The build stage installs all dependencies and compiles. The runtime stage copies only the compiled output and production dependencies — no compiler toolchain, no dev dependencies, no source maps in production. This reduces image size by 60–80% and eliminates build-time tools as attack surface.
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runtime
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+USER node
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+**Distroless base images:** For production, consider `gcr.io/distroless/nodejs` or `cgr.dev/chainguard/node`. These images contain only the runtime and its dependencies — no shell, no package manager, no OS utilities. Smaller attack surface, pass most container security scanners. Trade-off: harder to debug; use a separate debug image with a shell for incident investigation.
+
+**Non-root user:** Always run the container process as a non-root user (`USER node` or `USER nobody`). Combine with read-only filesystems (`--read-only`) and a writable tmpfs for temp files. Set resource limits (CPU, memory) to prevent noisy-neighbor problems in shared clusters.
+
+### Serverless Patterns
+
+**Cold start mitigation:** Cold starts add 200ms–2s of latency on the first request. Minimize cold starts by: keeping the function bundle small (tree-shake, avoid heavy dependencies), using provisioned concurrency for latency-sensitive paths, initializing database connections in the module scope (not inside the handler), and using connection proxies (RDS Proxy, PgBouncer) that maintain connection pools outside the function lifecycle.
+
+**Connection pooling:** Serverless functions can spawn thousands of instances simultaneously, overwhelming a traditional database's connection limit. Use a connection pooler (PgBouncer, RDS Proxy, Neon serverless driver) that sits between functions and the database. Configure pool size per function instance conservatively (1–5 connections).
+
+**Stateless design:** Serverless functions must be stateless. Store all session state, cache, and shared state in external services (Redis, DynamoDB). Write output to S3 or a database, never to the local filesystem.
+
+### Health Check Endpoints
+
+Every service must expose two health endpoints:
+
+**`GET /health` (liveness):** Returns 200 if the process is running and not deadlocked. Checked by the orchestrator to decide whether to restart the container. Must not check external dependencies — if the database is down, the container should not be restarted (it won't help). Respond within 50ms.
+
+**`GET /ready` (readiness):** Returns 200 if the service is ready to serve traffic; returns 503 otherwise. Checked before routing traffic to a new instance. Should verify critical dependencies: database connectivity, required cache availability. Remove from load balancer rotation when returning 503. Add a startup delay check so new instances don't receive traffic before warming up.
+
+Include response body with version, uptime, and dependency statuses for operational visibility.
+
+### Graceful Shutdown
+
+Handle `SIGTERM` (sent by Kubernetes, Docker, and process managers before killing the process):
+
+1. Stop accepting new connections (close the HTTP server's listening socket).
+2. Allow in-flight requests to complete (drain the request queue).
+3. Close database connections and message queue consumers cleanly.
+4. Flush buffered logs and metrics.
+5. Exit with code 0.
+
+Set a shutdown timeout (10–30 seconds). If draining takes longer, force exit. In Kubernetes, set `terminationGracePeriodSeconds` to match. Without graceful shutdown, deployments cause dropped requests and incomplete transactions.
+
+### Blue-Green and Canary Deploys
+
+**Blue-green:** Maintain two identical production environments (blue and green). Deploy the new version to the inactive environment, run smoke tests, then cut over traffic in one atomic switch. Instant rollback: switch traffic back. Cost: double the infrastructure during deployment.
+
+**Canary:** Route a small percentage of traffic (1%, 5%, 25%) to the new version. Monitor error rates, latency, and business metrics. Gradually increase the percentage if metrics are healthy, or roll back if they degrade. Better for catching issues that only appear under real traffic patterns. Requires traffic splitting at the load balancer or service mesh layer. Define explicit rollback criteria before deploying.
+
+### Infrastructure as Code
+
+Define all infrastructure in version-controlled configuration:
+
+- **Terraform / Pulumi**: Define cloud resources (load balancers, databases, queues, DNS) as code. Every infrastructure change goes through PR review and CI validation. `terraform plan` shows the diff before `terraform apply` makes changes.
+- **Docker Compose for local**: Mirror production infrastructure locally. Pin exact versions to prevent local-production drift.
+- **Kubernetes manifests**: Use Helm charts or Kustomize for templating. Keep environment-specific values in separate overlay files, not hardcoded in templates.
+
+Never create production infrastructure manually through a cloud console. Manual changes create configuration drift that causes incidents when the next Terraform apply overwrites them.
+
+### Resource Limits and Autoscaling
+
+Every container must have explicit resource requests and limits:
+
+- **CPU and memory requests**: The minimum resources the container needs. The scheduler uses these to place the container on a node with sufficient capacity.
+- **CPU and memory limits**: The maximum resources the container can consume. Exceeding memory limits causes an OOM kill; exceeding CPU limits causes throttling.
+- **Autoscaling**: Configure horizontal pod autoscaling (HPA) based on CPU utilization or custom metrics (request rate, queue depth). Set minimum replicas to handle baseline traffic without cold starts. Set maximum replicas to prevent runaway scaling from exhausting the cluster.
+
+Right-size by observing actual resource usage under load, not by guessing. Over-provisioning wastes money; under-provisioning causes throttling and OOM kills.
+
+### Deployment Checklist
+
+Before every production deployment: Are database migrations backward-compatible with both the old and new app version? Has the new version been validated in a staging environment? Are rollback procedures tested and documented? Are monitoring dashboards open and ready to observe the deployment? Is the on-call engineer aware of the deployment? Are feature flags configured to allow incremental rollout?

package/content/knowledge/backend/backend-dev-environment.md

@@ -0,0 +1,102 @@
+---
+name: backend-dev-environment
+description: Docker Compose for local databases and queues, database seeding and migration scripts, API testing tools, environment variable management, and local SSL setup
+topics: [backend, dev-environment, docker, migrations, testing, environment-variables]
+---
+
+A backend development environment that requires manual setup steps is a productivity drain and an onboarding failure. The standard should be: clone the repo, run one command, and have a fully functional local environment in under five minutes. Docker Compose is the primary tool for achieving this — it pins the exact versions of every external dependency and makes the environment reproducible across all developer machines.
+
+## Summary
+
+A backend dev environment should go from fresh checkout to running API in under five minutes. Docker Compose pins infrastructure dependencies (databases, caches, queues) to exact production-matching versions. Migrations are the source of truth for schema evolution; seed scripts provide a baseline dataset. Validate all environment variables at startup with a schema.
+
+## Deep Guidance
+
+### Docker Compose for Infrastructure
+
+Use Docker Compose to run all stateful infrastructure dependencies locally:
+
+- **Databases**: Pin the exact version that matches production. `postgres:16.2-alpine`, not `postgres:latest`. Version drift between local and production is a common source of query behavior differences.
+- **Cache / message queues**: Redis, RabbitMQ, Kafka, or SQS-compatible LocalStack — all run well in Compose. Define realistic resource limits to catch memory pressure issues locally.
+- **Health checks**: Add `healthcheck` to each service so `docker compose up --wait` blocks until the database is actually accepting connections, not just when the container starts.
+- **Named volumes**: Use named volumes (not bind mounts) for database data. This prevents accidental data loss when rebuilding containers.
+
+A `compose.yml` at the repo root is the convention. A `compose.override.yml` (gitignored) allows developer-specific customizations without touching the shared file.
+
+### Database Migrations
+
+Migrations are the source of truth for schema evolution. Never modify the database directly in development or production:
+
+- **Migration tool selection**: Flyway (Java, SQL-based), Liquibase (XML/YAML/SQL), Alembic (Python), golang-migrate, Prisma Migrate, or Knex — choose one and commit to it.
+- **Up/down migrations**: Every migration needs a reversible `down` script. Test the down migration in CI — it is the escape hatch for a bad deployment.
+- **Naming convention**: `V20240115__add_order_status_index.sql` — timestamp prefix ensures ordering is deterministic across branches.
+- **Run on startup**: In development, configure the app to run pending migrations automatically on startup. In production, run migrations as a pre-deployment step before traffic shifts.
+
+### Database Seeding
+
+Seed scripts provide a consistent baseline dataset for development and testing:
+
+- **Seed data separate from migrations**: Never embed seed data in migration files. Migrations are schema changes; seed scripts populate data for local development.
+- **Idempotent seeds**: Seed scripts must be safe to run multiple times. Use `INSERT ... ON CONFLICT DO NOTHING` or check for existence before inserting.
+- **Representative data**: Seed data should cover edge cases — empty states, boundary values, long strings — not just happy-path records.
+- **`npm run db:seed` or `make seed`**: One command to seed the database from a fresh state.
+
+### API Testing Tools
+
+Maintain machine-readable API test artifacts in the repository:
+
+- **Postman / Bruno collections**: Commit a `postman_collection.json` or `bruno/` directory with requests for every endpoint. Parameterize base URLs and auth tokens via environment files. Bruno is preferred for new projects — it uses plain-text files that diff well in git.
+- **curl scripts**: A `scripts/api/` directory with shell scripts exercising each endpoint is a low-overhead alternative. Always useful for CI health checks.
+- **REST Client files**: `.http` files (VS Code REST Client extension) are readable and committable. Good for simple endpoint documentation.
+
+### Environment Variable Management
+
+- **`.env.example`**: Committed to the repo. Contains all required variable names with placeholder values and comments explaining each. New developers copy this to `.env`.
+- **`.env`**: Gitignored. Developer-specific values. Never committed.
+- **Validation at startup**: Parse and validate the entire env config with a schema (Zod + `z.string().url()`, envalid) before the server starts. Fail with a clear error listing missing variables, not a cryptic runtime crash 30 minutes later.
+- **Secrets vs config**: Secrets (database passwords, private keys) are fetched from a secrets manager in production environments. Config (feature flags, timeouts) can be env vars.
+
+### Local SSL
+
+For services that require HTTPS locally (OAuth redirects, secure cookies, mixed-content testing):
+
+- **mkcert**: Generates locally trusted TLS certificates signed by a local CA. `mkcert localhost 127.0.0.1` produces a certificate that browsers trust without warnings.
+- **Caddy reverse proxy**: Configure Caddy as a local reverse proxy with automatic HTTPS to avoid configuring TLS in the app itself.
+
+### One-Command Setup
+
+The `make setup` or `./scripts/dev-setup.sh` target should: install required tool versions (via asdf or mise), pull Docker images, copy `.env.example` to `.env`, start Compose services, run migrations, and run seed scripts. A developer who has never seen the project should be running a working API in under five minutes.
+
+Document any manual steps that cannot be automated (hardware keys, corporate VPN certificates) in a `docs/dev-setup.md`. Every manual step is a future support ticket.
+
+### Database GUI Tools
+
+Provide a web-based database admin tool in the Compose stack for development:
+
+- **pgAdmin** or **Adminer**: Low-overhead database browsing. Adminer supports PostgreSQL, MySQL, SQLite, and MongoDB in a single container.
+- **TablePlus / DBeaver**: Recommend as desktop alternatives in the dev setup docs. Include connection strings for copy-paste.
+
+A developer who cannot see the data cannot debug the application. Make database access a one-click experience in the dev environment.
+
+### Test Data Generation
+
+Beyond simple seeds, provide tools for generating realistic test data at scale:
+
+- **Faker libraries**: `@faker-js/faker` (Node), `Faker` (Python), `gofakeit` (Go) generate realistic names, addresses, emails, and domain-specific values.
+- **Factory patterns**: Build factory functions that produce valid domain objects with sensible defaults and explicit overrides. `createOrder({ status: 'cancelled' })` should handle all required fields automatically.
+- **Volume seeding**: For performance testing locally, generate 10,000–100,000 rows. This catches query performance issues that are invisible at 100 rows. Include a `make seed-large` target for this scenario.
+
+### Hot Reloading Backend Services
+
+For Node.js services, use `tsx --watch` or `nodemon` for automatic restarts on file change:
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "dev:debug": "tsx watch --inspect src/server.ts"
+  }
+}
+```
+
+For Go: `air` provides automatic rebuild and restart. For Python: `uvicorn --reload` handles FastAPI and Starlette. For Rust: `cargo watch -x run`. The goal is sub-second feedback loops for backend changes matching what frontend developers expect from HMR.

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

@@ -0,0 +1,102 @@
+---
+name: backend-observability
+description: Structured logging, distributed tracing, RED method metrics, SLO-based alerting, and operational dashboards
+topics: [backend, observability, logging, tracing, metrics, alerting, opentelemetry, slo]
+---
+
+Observability is the ability to answer arbitrary questions about a system's behavior using its outputs alone — without deploying new code. Investing in structured logging, distributed tracing, and SLO-based alerting before the first incident makes the difference between a 5-minute diagnosis and a 5-hour outage.
+
+## Summary
+
+Observability requires three pillars: structured JSON logging with correlation IDs, distributed tracing via OpenTelemetry, and RED method metrics (Rate, Errors, Duration) for every service endpoint. SLO-based alerting replaces noisy threshold alerts. Build operational dashboards around these signals before the first incident, not after.
+
+## Deep Guidance
+
+### Structured Logging
+
+Log in JSON to make logs machine-parseable and searchable in aggregation systems (Datadog, Splunk, CloudWatch Logs Insights, Grafana Loki).
+
+**Standard fields every log line should include:**
+- `timestamp` — ISO 8601 with milliseconds
+- `level` — `debug`, `info`, `warn`, `error`
+- `message` — human-readable description
+- `service` — service name and version
+- `traceId` / `requestId` — correlation ID propagated from the incoming request
+
+**Log levels:**
+- `debug` — verbose development information; disabled in production by default
+- `info` — normal operational events (request received, job completed, user logged in)
+- `warn` — recoverable issues (retry attempted, fallback used, deprecated API called)
+- `error` — failures requiring attention (unhandled exception, external service down, database error)
+
+**Never log:** Passwords, tokens, API keys, credit card numbers, SSNs, or full request bodies of sensitive endpoints. Implement a logging middleware that redacts known-sensitive field names before any log line is written.
+
+**Correlation IDs:** Generate a UUID per request at the entry point (API gateway or first middleware). Propagate it through all downstream service calls via the `X-Request-ID` or `traceparent` header. Include it in every log line. This makes it possible to trace a single user request across all services and log streams.
+
+### Distributed Tracing
+
+Use OpenTelemetry (OTel) — the vendor-neutral standard for distributed tracing, metrics, and logs. Instrument once, export to any backend (Jaeger, Zipkin, Datadog APM, Honeycomb, AWS X-Ray).
+
+**Trace context propagation:** The OTel SDK automatically propagates `traceparent` and `tracestate` headers when you use instrumented HTTP clients. Always use the instrumented clients — never make raw HTTP calls that bypass propagation.
+
+**Auto-instrumentation:** Use OTel auto-instrumentation packages for your framework (Express, FastAPI, Spring Boot) to capture traces for all incoming requests and outgoing calls without manual spans.
+
+**Custom spans:** Add manual spans for business operations that span multiple functions: `processOrder`, `chargePayment`, `sendNotification`. Annotate spans with relevant attributes (user ID, order ID, amount). This provides visibility into where time is spent within a service.
+
+**Sampling:** In high-throughput services, trace every request at 100% to observe development/staging. In production, use head-based sampling (5–10%) to control costs while preserving statistically representative data. Always sample 100% of errored traces regardless of the sampling rate.
+
+### Metrics — RED Method
+
+The RED method (Rate, Errors, Duration) provides a minimal but complete view of service health:
+
+- **Rate:** Requests per second. Baseline normal traffic and alert on significant drops (traffic lost) or spikes (traffic surge, potential attack).
+- **Errors:** Request error rate as a percentage. Alert when the error rate exceeds the SLO threshold. Track by error type (4xx client errors vs. 5xx server errors).
+- **Duration:** Request latency. Track p50, p95, and p99. Alert on p99 exceeding the SLO latency threshold. Latency degradation often precedes error rate spikes.
+
+Instrument these three metrics for every service endpoint. For background workers, instrument job throughput (rate), job failures (errors), and job duration.
+
+### SLO-Based Alerting
+
+Define SLOs (Service Level Objectives) before writing alert rules. An SLO is a measurable target: "99.9% of requests complete successfully" or "p99 latency < 500ms over a 28-day window."
+
+**Error budget:** The tolerance implied by the SLO. A 99.9% availability SLO has a 0.1% error budget — about 44 minutes of downtime per month. Track error budget consumption and alert when it is burning faster than expected.
+
+**Burn rate alerts:** Alert when the error budget is being consumed at a rate that would exhaust it before the window ends. A burn rate of 2x means the budget runs out in half the window. Use multi-window burn rate alerts (fast burn: 5-minute window at 14x burn rate; slow burn: 1-hour window at 2x burn rate) to catch both sudden incidents and gradual degradations.
+
+Avoid threshold alerts on raw metrics — they generate too many false positives. SLO-based alerting reduces alert fatigue and ensures alerts correspond to actual user impact.
+
+### Dashboards
+
+Build dashboards around the RED metrics plus infrastructure health. Every service dashboard should show: request rate, error rate, p50/p95/p99 latency, error budget remaining, database query latency, and downstream service call rates.
+
+Add runbook links to every alert. An alert without a runbook wastes incident response time.
+
+### Log Aggregation Pipeline
+
+Production logging requires a pipeline from application to searchable dashboard:
+
+1. **Application** emits structured JSON logs to stdout (never to files in containerized environments)
+2. **Log shipper** (Fluentd, Fluent Bit, Vector, or the platform's native agent) collects logs from stdout
+3. **Log store** (Elasticsearch, Grafana Loki, CloudWatch Logs, Datadog) indexes and stores logs
+4. **Dashboard** (Kibana, Grafana, CloudWatch Insights) provides search, filtering, and alerting
+
+Keep log retention proportional to the debugging window: 14–30 days for verbose logs, 90 days for error logs, 1 year for audit logs. Storage costs scale linearly with retention — budget accordingly.
+
+### Infrastructure Metrics
+
+Beyond application metrics, monitor the infrastructure layer:
+
+- **Container metrics**: CPU usage, memory usage, restart count, OOM kill events
+- **Database metrics**: Active connections, query latency p95, replication lag, disk usage
+- **Queue metrics**: Queue depth, consumer lag, DLQ depth, message age
+- **Network metrics**: Request rate at the load balancer, 5xx rate, connection errors
+
+Set alerts on infrastructure metrics that precede application failures: database connection pool saturation, disk usage above 80%, and replication lag above 10 seconds. Catching these early prevents user-facing incidents.
+
+### Incident Response Observability
+
+During an incident, observability tools must answer three questions in under 5 minutes:
+
+1. **What changed?** — Deployment timeline overlaid on error rate graphs. Correlate the incident start time with the most recent deployment.
+2. **What is affected?** — Service dependency map showing which services are degraded. Error rate by endpoint to identify the blast radius.
+3. **What is the root cause?** — Distributed trace for a failing request showing where time is spent and where errors originate. Log search by `requestId` for the specific failure context.

package/content/knowledge/backend/backend-project-structure.md

@@ -0,0 +1,100 @@
+---
+name: backend-project-structure
+description: Canonical directory layout for backend services — routes/controllers, services, models/repositories, middleware, utils, config resolution, and dependency injection patterns
+topics: [backend, project-structure, architecture, dependency-injection, layers]
+---
+
+A well-organized backend project is readable to a new engineer in minutes. The directory layout should communicate the architecture: which layer owns which responsibility, where to add a new feature, and where to find any piece of behavior. The most common structural failure is mixing concerns — business logic in controllers, database calls in services, HTTP parsing in repositories. Enforce boundaries through structure first, tooling second.
+
+## Summary
+
+A backend project structure should communicate its architecture at a glance: routes own HTTP registration, handlers translate HTTP to service calls, services contain business logic, and repositories abstract data access. Config is loaded and validated at startup. Dependencies are composed explicitly via constructor injection at a single composition root.
+
+For small services, group by layer. For large codebases (10+ engineers or 20+ domain concepts), reorganize by feature/domain with layer sub-directories and enforce import boundaries between feature modules.
+
+## Deep Guidance
+
+### Canonical Directory Layout
+
+```
+src/
+  routes/          # HTTP route definitions and handler registration
+  handlers/        # (or controllers/) Request parsing, validation, response formatting
+  services/        # Business logic — no HTTP, no database drivers
+  repositories/    # (or models/) Data access — queries, mutations, ORM models
+  middleware/      # Cross-cutting HTTP concerns: auth, logging, rate limiting
+  utils/           # Pure utility functions: date formatting, hashing, parsing
+  config/          # Configuration loading and validation
+  types/           # Shared TypeScript types and interfaces
+  errors/          # Custom error classes and error code definitions
+  jobs/            # Background jobs, queue workers, scheduled tasks
+  events/          # Event emitters, message queue publishers/consumers
+  app.ts           # Application composition root
+  server.ts        # HTTP server startup (separate from app composition)
+```
+
+### Layer Responsibilities
+
+**routes/** (or routers): Define HTTP paths, methods, and which handler each maps to. No logic — only route registration. In Express: `router.post('/orders', ordersHandler.create)`. In Fastify: schema-decorated route objects.
+
+**handlers/** (or controllers/): Translate HTTP into service calls. Parse and validate request parameters and bodies. Call one or more services. Format and send the HTTP response. No business rules, no SQL.
+
+**services/**: Contain all business logic. Receive plain objects (not request/response objects). Return plain objects or throw domain errors. Depend on repository interfaces, not concrete implementations — this enables testing without a real database.
+
+**repositories/**: Abstract data access behind a consistent interface. A `UserRepository` exposes `findById(id)`, `create(data)`, `update(id, data)` — callers never see SQL or ORM query syntax. Swap implementations (Postgres ↔ in-memory ↔ DynamoDB) without changing services.
+
+**middleware/**: Applied globally or per-route at the framework level. Authentication, request ID injection, body parsing, rate limiting, CORS headers. Each middleware does one thing.
+
+**config/**: Load environment variables, validate them with a schema (Zod, Joi, envalid), and export a typed config object. Never access `process.env` directly outside this module.
+
+### Config Resolution
+
+Config follows a priority order: environment variables override file-based config, which overrides built-in defaults. Validate the entire config object at startup with a strict schema — fail fast with a clear error if a required variable is missing. Never lazy-load config in a request handler; config should be loaded and validated once at process start.
+
+Separate config from secrets. Config (feature flags, timeouts, rate limits) lives in environment variables or a config file. Secrets (database passwords, API keys) are fetched from a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler) at startup or via a sidecar — never committed to version control.
+
+### Dependency Injection Patterns
+
+Avoid module-level singletons for dependencies with side effects (database connections, HTTP clients). Instead, compose dependencies explicitly:
+
+- **Constructor injection**: Pass dependencies as constructor arguments to service and repository classes. `new OrderService(orderRepository, paymentClient, eventEmitter)`. Testable without framework magic.
+- **Composition root**: Wire all dependencies together in `app.ts` or a dedicated `container.ts`. This is the only place that instantiates concrete implementations.
+- **DI frameworks**: InversifyJS, tsyringe, or NestJS's built-in IoC container add decorator-based injection. Use only if the manual wiring becomes unmanageable — DI frameworks add complexity and build overhead.
+
+### Feature-Based Structure (Large Codebases)
+
+When a codebase grows beyond ~10 engineers or ~20 domain concepts, flat layer directories become unwieldy. Reorganize by feature/domain with layer sub-directories:
+
+```
+src/
+  orders/
+    orders.handler.ts
+    orders.service.ts
+    orders.repository.ts
+    orders.types.ts
+    orders.test.ts
+  users/
+    users.handler.ts
+    users.service.ts
+    ...
+  shared/
+    middleware/
+    utils/
+    config/
+```
+
+This makes the blast radius of a domain change obvious and allows teams to own vertical slices. Enforce a rule: code in `orders/` may not import from `users/` — communication happens through a service interface or event. Cross-domain dependencies are always explicit.
+
+### When to Create a New Layer
+
+The urge to add layers (`managers/`, `helpers/`, `transformers/`) should be resisted unless the new concept is meaningfully distinct and will appear in more than one place. Every layer is a conceptual tax on new engineers. Prefer a clear violation of the existing convention to an ad hoc proliferation of vaguely named directories.
+
+### Test File Organization
+
+Choose one test file placement pattern and enforce it project-wide:
+
+- **Co-located**: `order-service.ts` and `order-service.test.ts` in the same directory. Easier to find the test for a given file. Preferred for unit tests.
+- **Mirror directory**: `src/services/order-service.ts` and `tests/services/order-service.test.ts`. Keeps the `src/` directory clean. Preferred when test files significantly outnumber source files.
+- **Integration tests**: Always in a dedicated `tests/integration/` or `tests/e2e/` directory. These test cross-layer behavior and do not belong next to any single source file.
+
+Whichever pattern you choose, enforce it in the ESLint configuration so new files follow the convention automatically.