@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/core/operations-runbook.md

@@ -1,257 +1,72 @@
 ---
 name: operations-runbook
-description: Dev environment setup, CI/CD pipeline design, deployment, monitoring, and incident response
-topics: [operations, cicd, deployment, monitoring, dev-environment, incident-response, local-dev]
+description: Deployment pipeline, deployment strategies, monitoring, alerting, and incident response
+topics: [operations, ci-cd, deployment, monitoring, incident-response, alerting, rollback]
 ---
 
-## Dev Environment Setup
+## Summary
 
-A productive development environment lets a developer (or AI agent) go from cloning the repo to running the application in under 5 minutes. The fewer manual steps, the fewer things that can go wrong.
+## Dev Environment Reference
 
-### Local Development Prerequisites
+Local development setup (prerequisites, env vars, one-command setup, database, hot reload, common commands, troubleshooting) is defined in `docs/dev-setup.md`, created by the Dev Setup prompt. The operations runbook should reference it rather than redefine it.
 
-Document every system-level dependency with exact versions:
+**Operations-specific additions** (not covered by dev-setup):
 
-| Dependency | Version | Why |
-|------------|---------|-----|
-| Node.js | 20.x LTS | Runtime |
-| Python | 3.12+ | Backend scripts |
-| PostgreSQL | 16+ | Primary database |
-| Redis | 7+ | Caching and sessions |
-| Docker | 24+ | Database containers (optional) |
+### Environment-Specific Configuration
 
-**Version management:** Recommend a version manager for each language runtime:
-- Node.js: `nvm`, `fnm`, or `.nvmrc` for automatic version switching
-- Python: `pyenv` with `.python-version`
-- Ruby: `rbenv` with `.ruby-version`
+Document how environment variables differ across environments:
 
-Check in a `.node-version` or `.nvmrc` file so tools auto-select the correct version.
+| Variable | Local | Staging | Production |
+|----------|-------|---------|------------|
+| `APP_ENV` | development | staging | production |
+| `DATABASE_URL` | localhost | staging-db-host | prod-db-host |
+| `LOG_LEVEL` | debug | info | warn |
 
-### Environment Variables
+### Secrets Management
 
-Every project needs a clear environment variable strategy:
+Production secrets should never be in code or `.env` files:
+- Use a secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault, Doppler)
+- Rotate secrets on a schedule (90 days for API keys, 365 days for service accounts)
+- Audit access to secrets
+- Document which secrets exist, where they're stored, and who can access them
 
-**`.env.example`** — Template committed to git with all required variables, default values for local development, and comments explaining each variable:
+## Deployment Pipeline
 
-```bash
-# Application
-APP_PORT=3000                    # Port for the dev server
-APP_ENV=development              # development | staging | production
-APP_URL=http://localhost:3000    # Base URL for the app
-
-# Database
-DATABASE_URL=postgresql://localhost:5432/myapp_dev  # Local PostgreSQL
-DATABASE_POOL_SIZE=5             # Connection pool size
-
-# Authentication
-JWT_SECRET=local-dev-secret-change-in-production  # JWT signing key
-SESSION_SECRET=local-session-secret               # Session cookie secret
-
-# External Services (optional for local dev)
-# STRIPE_SECRET_KEY=sk_test_...  # Uncomment when testing payments
-# SENDGRID_API_KEY=SG....       # Uncomment when testing emails
-```
-
-**`.env`** — Actual local configuration, gitignored. Created by copying `.env.example`.
-
-**Required vs. optional:** Clearly mark which variables are required for the app to start and which are optional (features degrade gracefully without them).
-
-### One-Command Setup
-
-Provide a single command that installs all dependencies, creates the database, runs migrations, seeds data, and starts the dev server:
-
-```bash
-# First time setup
-make setup    # or: npm run setup
-
-# Daily development
-make dev      # or: npm run dev
-```
-
-The setup command should be idempotent — safe to run twice without breaking anything.
-
-### Database Setup for Local Development
-
-**Option A: Local installation**
-- Install database server natively
-- Create dev database: `createdb myapp_dev` (PostgreSQL)
-- Run migrations: `make db-migrate`
-- Seed data: `make db-seed`
-
-**Option B: Docker Compose**
-```yaml
-services:
-  db:
-    image: postgres:16
-    ports: ["5432:5432"]
-    environment:
-      POSTGRES_DB: myapp_dev
-      POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
-    volumes:
-      - pgdata:/var/lib/postgresql/data
-
-  redis:
-    image: redis:7
-    ports: ["6379:6379"]
-
-volumes:
-  pgdata:
-```
-
-Docker Compose is convenient for managing service dependencies but adds startup time and complexity. For simple stacks (SQLite, single service), skip Docker entirely.
-
-**Option C: SQLite for development**
-- No setup required
-- Create database file on first run
-- Fast, zero-configuration
-- Trade-off: behavior differences from production PostgreSQL (no JSONB, different SQL dialect)
-
-### Hot Reloading Configuration
-
-The dev server must reload automatically when code changes:
-
-- **Frontend:** Vite HMR (React, Vue, Svelte), Next.js Fast Refresh, or webpack HMR
-- **Backend (Node.js):** `tsx watch`, `nodemon`, or `ts-node-dev` for TypeScript; `node --watch` for plain Node
-- **Backend (Python):** `uvicorn --reload` (FastAPI), `flask run --debug` (Flask), `manage.py runserver` (Django)
-- **Full-stack:** Run frontend and backend concurrently with a process manager (`concurrently`, `honcho`, or Makefile with `&`)
-
-### Common Dev Commands
-
-Every project should have a consistent set of commands. Use whatever mechanism fits the stack:
-
-| Command | Purpose | Implementation |
-|---------|---------|---------------|
-| `make dev` | Start dev server with hot reload | Frontend + backend concurrently |
-| `make test` | Run all tests | Test runner with coverage |
-| `make test-watch` | Run tests in watch mode | Test runner in watch mode |
-| `make lint` | Check code style | Linter for each language |
-| `make format` | Auto-fix formatting | Formatter for each language |
-| `make db-migrate` | Run pending migrations | Migration tool |
-| `make db-seed` | Seed database with sample data | Seed script |
-| `make db-reset` | Drop, recreate, migrate, seed | Compose the above |
-| `make check` | Run all quality gates | lint + type-check + test |
-
-Commands should be:
-- Short and memorable (not `npx jest --runInBand --coverage --passWithNoTests`)
-- Documented with help text
-- Idempotent where possible
-- Fast enough to run frequently
-
-### Troubleshooting Guide
-
-Document solutions for common development issues:
-
-**Port already in use:**
-```bash
-lsof -i :3000  # Find the process
-kill -9 <PID>  # Kill it
-```
-
-**Database connection refused:**
-- Is the database running? `pg_isready` or `docker ps`
-- Is the connection string correct? Check `.env`
-- Is the port correct? Check for port conflicts
-
-**Dependencies out of sync:**
-```bash
-rm -rf node_modules && npm install  # Node.js
-rm -rf .venv && python -m venv .venv && pip install -r requirements.txt  # Python
-```
-
-**Migrations out of date:**
-```bash
-make db-migrate  # Run pending migrations
-make db-reset    # Nuclear option: start fresh
-```
-
-## CI/CD Pipeline
+The base CI pipeline (lint + test on PRs) is configured by the Git Workflow prompt in `.github/workflows/ci.yml`. The operations runbook extends this with production deployment stages — it does not redefine the base CI.
 
 ### Pipeline Architecture
 
-A CI/CD pipeline automates the path from code commit to production deployment. Design it in stages:
-
 ```
-Push to branch
-  -> Stage 1: Fast checks (30s)
-       Lint, format check, type check
-  -> Stage 2: Tests (2-5 min)
-       Unit tests, integration tests (parallel)
-  -> Stage 3: Build (1-2 min)
-       Compile, bundle, generate artifacts
-  -> Stage 4: Deploy (2-5 min, only on main)
-       Deploy to staging/production
-
-PR merge to main
-  -> All stages above
-  -> Stage 5: Post-deploy verification
-       Smoke tests against deployed environment
+Existing CI (from git-workflow — already configured):
+  -> Stage 1: Fast checks (30s) — lint, format, type check
+  -> Stage 2: Tests (2-5 min) — unit + integration in parallel
+
+Operations adds (main branch only):
+  -> Stage 3: Build (1-2 min) — compile, bundle, generate artifacts
+  -> Stage 4: Deploy (2-5 min) — deploy to staging/production
+  -> Stage 5: Post-deploy verification — smoke tests
 ```
 
-### Stage Design
-
-**Stage 1: Fast Checks**
-- Run on every push and PR
-- Fail fast: if linting fails, don't bother running tests
-- Cache dependencies between runs
-- Target: <30 seconds
-
-```yaml
-# GitHub Actions example
-lint:
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with: { node-version-file: '.nvmrc' }
-    - run: npm ci --ignore-scripts
-    - run: npm run lint
-    - run: npm run type-check
-```
-
-**Stage 2: Tests**
-- Run unit and integration tests in parallel
-- Use a service container for the test database
-- Upload coverage reports as artifacts
-- Target: <5 minutes
-
-```yaml
-test:
-  runs-on: ubuntu-latest
-  services:
-    postgres:
-      image: postgres:16
-      env:
-        POSTGRES_DB: test
-        POSTGRES_PASSWORD: test
-      ports: ['5432:5432']
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-    - run: npm ci
-    - run: npm run test:ci
-      env:
-        DATABASE_URL: postgresql://postgres:test@localhost:5432/test
-```
+### Stage 3: Build
 
-**Stage 3: Build**
 - Compile TypeScript, bundle frontend assets, generate Docker image
 - Verify the build artifact is valid (start the server and check health endpoint)
 - Store the build artifact for deployment
+- Only runs after Stages 1-2 pass
+
+### Stage 4: Deploy
 
-**Stage 4: Deploy**
 - Only runs on main branch (after PR merge)
 - Deploy the build artifact from Stage 3
 - Run database migrations before starting new version
 - Verify health check after deployment
 
-### Parallelization and Caching
-
-**Parallel jobs:** Run lint, unit tests, and integration tests as separate parallel jobs. The total pipeline time equals the longest individual job, not the sum.
-
-**Dependency caching:** Cache `node_modules/` (keyed by `package-lock.json` hash), Python virtual environments, Docker layer cache. This turns a 60-second install into a 5-second cache restore.
+### Stage 5: Post-Deploy Verification
 
-**Test parallelization:** Split test files across multiple runners. Most test frameworks support `--shard` or `--split` modes.
+- Run smoke tests against the deployed environment
+- Verify critical user flows work end-to-end
+- Check external dependency connectivity
+- If smoke tests fail: trigger automatic rollback
 
 ### Artifact Management
 
@@ -260,6 +75,8 @@ test:
 - Tag artifacts with the git SHA for traceability
 - Set retention policies (keep last 30 days, keep releases forever)
 
+## Deep Guidance
+
 ## Deployment Strategies
 
 ### Blue-Green Deployment
@@ -502,8 +319,6 @@ Define service level targets for the application:
 
 **Alert fatigue.** Too many alerts firing for non-critical issues. The on-call person starts ignoring alerts because most are noise. A real incident gets missed. Fix: every alert must have a clear response action. Remove alerts that routinely fire without requiring action.
 
-**No local dev story.** "It works on the CI server" but developers can't run the application locally. Fix: document the local setup, make it one command, test it regularly by having new team members follow the instructions.
-
 **Manual deployment steps.** Deployment requires an engineer to SSH into a server and run commands. This is error-prone, unreproducible, and blocks deployment on individual availability. Fix: fully automate deployment. A merge to main should trigger deployment automatically.
 
 **No monitoring before launch.** Monitoring is added after the first incident, when it's most needed and least available. Fix: set up monitoring as part of the infrastructure phase, before any user traffic.

package/knowledge/core/project-structure-patterns.md

@@ -0,0 +1,231 @@
+---
+name: project-structure-patterns
+description: Directory layout patterns by framework, module organization, and file placement rules
+topics: [project-structure, directory-layout, module-organization, file-placement, monorepo, colocation]
+---
+
+# Project Structure Patterns
+
+Directory structure is the physical manifestation of architectural decisions. A well-organized project communicates its architecture through the file tree alone — a new developer should understand the system's boundaries by reading directory names. This knowledge covers core layout patterns, framework-specific conventions, and the rules that keep structures clean as projects grow.
+
+## Summary
+
+### Core Patterns
+
+Three fundamental approaches to organizing source code:
+
+1. **Feature-Based (Vertical Slices)** — Group by business domain. Each feature directory contains its own components, services, tests, and types. Best for: domain-rich applications, teams organized by feature.
+2. **Layer-Based (Horizontal Layers)** — Group by technical concern. Separate directories for controllers, services, repositories, models. Best for: small projects, CRUD-heavy apps, teams organized by specialization.
+3. **Hybrid** — Feature-based at the top level, layer-based within each feature. Most common in practice. Combines domain clarity with technical organization.
+
+### The Co-Location Principle
+
+Files that change together should live together. A feature's component, styles, tests, types, and utilities belong in the same directory — not scattered across `components/`, `styles/`, `tests/`, `types/`, and `utils/`. Co-location reduces the cognitive cost of changes.
+
+### The Shared Code Rule
+
+Code belongs in a shared directory (`shared/`, `common/`, `lib/`) only when it has 2 or more consumers. A "shared" utility used by one feature is misplaced — it belongs in that feature's directory. Premature extraction into shared code creates coupling without benefit.
+
+### When to Restructure
+
+Restructure when: navigation becomes difficult (too many files in one directory), features are tangled (changing one feature touches many directories), or onboarding developers consistently get lost. Do not restructure for aesthetic reasons or because a blog post recommended a different layout.
+
+### Test Placement
+
+Co-located tests (`service.test.ts` next to `service.ts`) for unit tests — easy to find, move with refactors. Mirror directory (`tests/` mirroring `src/`) for integration and E2E tests that span modules.
+
+### Config vs. Application Code
+
+Tooling config files (`tsconfig.json`, `eslint.config.js`, `Makefile`) live at project root by convention. Application config (`src/config/`) holds runtime settings (database URLs, feature flags). Never mix the two locations.
+
+## Deep Guidance
+
+### Feature-Based Structure
+
+Feature-based organization maps directly to the product's domain model:
+
+```
+src/
+  features/
+    auth/
+      components/LoginForm.tsx, LoginForm.test.tsx
+      hooks/useAuth.ts, useAuth.test.ts
+      services/auth-service.ts, auth-service.test.ts
+      types.ts
+      index.ts           # public API barrel — other features import from here
+    billing/
+      components/, hooks/, services/, types.ts, index.ts
+  shared/
+    components/          # truly shared: Button, Modal, Input
+    hooks/               # truly shared: useDebounce, useLocalStorage
+    utils/               # truly shared: formatDate, validateEmail
+```
+
+**The index.ts barrel** defines each feature's public API. Other features import from `@/features/auth`, never from internal paths. This creates explicit boundaries — internal refactoring cannot break consumers.
+
+**When it breaks down**: Heavy cross-cutting concerns (every feature needs auth context, analytics, error boundaries). Solution: shared infrastructure lives in `shared/` or `infrastructure/`.
+
+### Layer-Based Structure
+
+Layer-based organization mirrors the technical architecture:
+
+```
+src/
+  controllers/auth-controller.ts, billing-controller.ts
+  services/auth-service.ts, billing-service.ts
+  repositories/user-repository.ts, invoice-repository.ts
+  models/user.ts, invoice.ts
+  middleware/auth-middleware.ts, logging-middleware.ts
+```
+
+Clear dependency direction: controllers depend on services, services on repositories, never reverse. Breaks down beyond ~20 files per directory — that signals the need for feature grouping.
+
+### Framework-Specific Patterns
+
+#### Next.js (App Router)
+
+```
+app/
+  layout.tsx, page.tsx
+  (auth)/login/page.tsx, signup/page.tsx    # route group (no URL segment)
+  dashboard/layout.tsx, page.tsx, settings/page.tsx
+  api/users/route.ts
+src/features/, src/shared/
+```
+
+Conventions: `page.tsx` defines routes, `layout.tsx` for nested layouts, `loading.tsx` for suspense, `error.tsx` for error boundaries. Route groups `(name)` organize without URL impact. Server Components default — mark `'use client'` explicitly.
+
+#### Express / Fastify
+
+```
+src/
+  routes/auth.routes.ts, index.ts     # route definitions (thin)
+  handlers/auth.handler.ts            # request/response logic
+  services/, repositories/, models/, middleware/
+  app.ts, server.ts
+```
+
+Separate routes from handlers. Routes define paths and middleware chains. Handlers contain logic and are independently testable.
+
+#### FastAPI
+
+```
+src/app/
+  routers/auth.py, billing.py
+  services/, repositories/
+  models/          # Pydantic schemas
+  db/              # SQLAlchemy models
+  core/config.py, security.py, dependencies.py
+  main.py
+```
+
+Convention: `routers/` not `routes/`. Pydantic models for API schemas, separate ORM models for database. Dependency injection via `Depends()`.
+
+#### Go
+
+```
+cmd/server/main.go, cli/main.go
+internal/
+  auth/handler.go, service.go, repository.go, handler_test.go
+  billing/...
+  platform/postgres/, redis/, http/
+pkg/validate/, money/
+```
+
+Convention: `cmd/` for entry points, `internal/` for private code (compiler-enforced), `pkg/` for reusable libraries. Flat package structure preferred.
+
+### Monorepo Patterns
+
+Use a monorepo when packages share types/utilities, you need atomic cross-package changes, or packages are tightly coupled. Do not use when packages are independently deployable with no shared code.
+
+```
+packages/
+  web/src/, package.json
+  api/src/, package.json
+  shared/src/, package.json
+  config/eslint-base.js, tsconfig-base.json
+package.json       # workspace configuration
+turbo.json         # build orchestration
+```
+
+Packages import from `@myorg/shared`, never from relative paths across package boundaries. Workspace resolution handles local development.
+
+### The Hybrid Pattern — Detailed Example
+
+The hybrid approach is the most practical for medium-to-large applications. Features at the top, layers within:
+
+```
+src/
+  features/
+    auth/
+      controller.ts      # HTTP handler / route handler
+      service.ts          # Business logic
+      repository.ts       # Data access
+      model.ts            # Domain types
+      service.test.ts     # Unit tests co-located
+      controller.test.ts
+    billing/
+      controller.ts
+      service.ts
+      repository.ts
+      model.ts
+      ...
+  shared/
+    middleware/           # Cross-cutting: auth, logging, rate-limit
+    utils/               # Truly shared utilities (2+ consumers)
+    types/               # Shared type definitions
+  config/                # Application configuration
+  app.ts                 # Application bootstrap
+  server.ts              # Server entry point
+```
+
+Each feature is self-contained. Adding a new feature means creating a new directory — no changes to existing features. Deleting a feature means removing one directory (plus cleanup of any shared references).
+
+### Config File Placement
+
+Config files live in the project root by universal convention: `package.json`, `tsconfig.json`, `eslint.config.js`, `pyproject.toml`, `go.mod`, `Makefile`, `Dockerfile`. Do not move them into a `config/` directory — tooling expects them at root. Application configuration (database URLs, feature flags) belongs in `src/config/`.
+
+### Generated File Handling
+
+Generated files (API clients, GraphQL types, migrations) need special treatment:
+- **Dedicated directory**: `src/generated/` or `__generated__/` — clearly non-hand-edited
+- **Linter exclusion**: `**/generated/**` excluded from lint configs
+- **Regeneration command**: `make generate` documented in CLAUDE.md
+- **Git decision**: Generated-from-committed-specs can be gitignored; generated-from-external-sources should be committed
+
+### Entry Points and Barrel Files
+
+**Entry points** (`main.ts`, `server.ts`, `index.ts` at project root, route files) are imported by the framework, not by other source files. Structure evals must exclude them from orphan detection.
+
+**Barrel files** (`index.ts` in feature directories) re-export the feature's public API. Rules:
+- One barrel per feature directory
+- Only re-export what other features need — internal utilities stay unexported
+- Never create barrel files in leaf directories (they add indirection without value)
+- Avoid circular dependencies by keeping barrel imports one-directional (features import from shared, never reverse)
+
+### Common Anti-Patterns
+
+**God Directories**: `src/utils/` has 47 files, `src/components/` has 93. Fix: move utilities into their consuming features. Only genuinely shared items (3+ consumers) stay in `shared/`.
+
+**Premature Abstraction into Shared**: Creating `shared/formatCurrency.ts` "because someone might need it later." Fix: enforce the 2+ consumer rule. Code enters `shared/` only when a second consumer actually needs it.
+
+**Inconsistent Depth**: 5-level nesting next to 2-level nesting. Fix: define maximum nesting depth (3-4 levels from `src/`). Deep nesting signals a feature should be split.
+
+**Orphaned Files**: Files not imported by anything and not entry points, accumulated during refactors. Fix: structure evals detect orphans in CI.
+
+### Migration Between Structures
+
+Moving from layer-based to feature-based (the most common migration):
+
+1. Create feature directories alongside existing layers
+2. Move one feature at a time — start with the most self-contained (fewest cross-feature dependencies)
+3. Update imports as you move — no redirect files
+4. Verify tests pass after each feature migration
+5. Delete empty layer directories once all features extracted
+6. Update `docs/project-structure.md`
+
+Move one feature per PR. Each PR leaves the project working with passing tests. Five small PRs over a week is safer than one massive PR touching every file.
+
+## See Also
+
+- [system-architecture](../core/system-architecture.md) — Architecture manifests in file structure