service-template-express/CLAUDE.md

Service conventions

• Stack: Express 5, TypeScript ESM (tsc), Node 22, pg + node-pg-migrate, ioredis, pino/pino-http, zod, vitest + supertest.
• Do NOT rename npm scripts (lint, test, format:check, build, migrate): the shared CI composite actions call them.
• Config: all env parsed once in src/lib/config.ts (zod); add new vars there.
• Logging contract (log pipeline depends on it): JSON per line on stdout with level,time,msg,service,version; requests add req.id,req.method,req.url,res.statusCode,responseTime.
• Health contract: /healthz liveness (always 200), /readyz readiness (checks configured Postgres/Redis, else 503 JSON).
• Seams: cross-cutting modules in src/lib/, endpoints in src/routes/ wired in src/app.ts.
• Feature flags: only via deps.flags (src/lib/flags.ts, Unleash); never import unleash-client elsewhere. Unset UNLEASH_URL = all flags off.
• Runtime config: only via deps.runtimeConfig.get() (src/lib/runtime-config.ts); keys + defaults in src/runtime-config.schema.ts. Never secrets. Never mount the ConfigMap with subPath (breaks hot reload).
• Migrations: migrations/*.sql, run in-cluster by an ArgoCD PreSync Job using this same image.
• Deploy: push to main -> Forgejo CI -> image -> gitops bump -> ArgoCD. Never kubectl apply by hand.