# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Node.js + Express + Drizzle ORM + Zod validation + Docker project.

Stack: Node.js + Express, Drizzle ORM, Zod validation, Docker.

## Commands

- Dev server: `npm run dev`
- Build: `npm run build`
- Type-check: `npx tsc --noEmit`
- Generate migration: `npx drizzle-kit generate`
- Apply migrations: `npx drizzle-kit migrate`
- Local services: `docker compose up -d`

## Project structure

- `src/routes/` for routers, `src/services/` for business logic, `src/middleware/` for middleware.
- Keep route handlers thin: parse input, call a service, return a response.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Node.js + Express

- Express 5 forwards rejected promises from async handlers to the error middleware; do not wrap every handler in try/catch.
- Have one central error-handling middleware that logs the error and returns a consistent JSON error shape.
- Validate every request body, query and param before using it.
- Use `helmet`, a strict CORS allow-list and rate limiting on public endpoints.
- Read config from env vars once at startup in a typed config module; fail fast if a required var is missing.
- Return correct HTTP status codes (400 validation, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict).

## Drizzle ORM

- Schema lives in TypeScript (`db/schema.ts`). Generate SQL migrations with `drizzle-kit generate` and commit them.
- `drizzle-kit push` is for local prototyping only, never for production databases.
- Infer types with `typeof table.$inferSelect` / `$inferInsert` instead of duplicating interfaces.
- Use the query builder or `sql` template tag; never build SQL with string concatenation.
- Use `db.transaction()` for multi-step writes.

## Zod validation

- Validate all untrusted input (request bodies, form data, env vars, third-party API responses) with a Zod schema at the boundary.
- Derive TypeScript types from schemas with `z.infer<typeof schema>`; do not hand-write duplicate types.
- Use `safeParse` where you need to return validation errors to the user.

## Docker

- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.

## Reference docs

- [Express docs](https://expressjs.com)
- [Drizzle docs](https://orm.drizzle.team/docs/overview)
- [Zod docs](https://zod.dev)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)