# 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`.
- 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.