Express + Drizzle + Docker rules for AI coding agents

# 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/)

# CLAUDE.md - this project

Project instructions for Claude Code.

## 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/)

---
description: "Core rules for this project"
alwaysApply: true
---

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

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

---
description: "Node.js + Express conventions: Express 5 REST API in TypeScript on Node.js."
globs: src/**/*.ts
alwaysApply: false
---

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

Docs: https://expressjs.com

---
description: "Drizzle ORM conventions: SQL-like TypeScript ORM with drizzle-kit migrations."
globs: db/**/*.ts, src/db/**/*.ts, drizzle/**
alwaysApply: false
---

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

Docs: https://orm.drizzle.team/docs/overview

---
description: "Zod validation conventions: Runtime schema validation with Zod."
globs: **/*.ts, **/*.tsx
alwaysApply: false
---

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

Docs: https://zod.dev

---
description: "Docker conventions: Containerised builds and local services with Docker."
globs: Dockerfile, **/Dockerfile, compose.yaml, docker-compose.yml, .dockerignore
alwaysApply: false
---

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

Docs: https://docs.docker.com/build/building/best-practices/

# Cursor rules - this project

You are an expert Node.js + Express, Drizzle ORM, Zod validation, Docker engineer working on this codebase. Follow these rules.

## 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/)

# Copilot instructions - this 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`

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

---
applyTo: "src/**/*.ts"
---

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

---
applyTo: "db/**/*.ts,src/db/**/*.ts,drizzle/**"
---

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

---
applyTo: "**/*.ts,**/*.tsx"
---

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

---
applyTo: "Dockerfile,**/Dockerfile,compose.yaml,docker-compose.yml,.dockerignore"
---

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

---
trigger: always_on
---

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

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

---
trigger: glob
globs: src/**/*.ts
---

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

---
trigger: glob
globs: db/**/*.ts, src/db/**/*.ts, drizzle/**
---

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

---
trigger: glob
globs: **/*.ts, **/*.tsx
---

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

---
trigger: glob
globs: Dockerfile, **/Dockerfile, compose.yaml, docker-compose.yml, .dockerignore
---

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

# GEMINI.md - this project

Project context for Gemini CLI.

## 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/)