# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

Eyrun is an API-only service built with Node.js, TypeScript, Fastify, and PostgreSQL (via Drizzle ORM).

## Commands

```bash
pnpm dev              # Start dev server with hot reload (tsx watch)
pnpm build            # Compile TypeScript to dist/
pnpm start            # Run compiled output (node dist/server.js)
pnpm db:generate      # Generate migration files from schema changes
pnpm db:migrate       # Apply pending migrations to the database
pnpm db:studio        # Open Drizzle Studio (visual DB browser)
```

## Architecture

**Entry point**: `src/server.ts` creates the app and starts listening.

**App factory**: `src/app.ts` — `buildApp()` creates a Fastify instance, registers plugins and routes. This pattern makes it easy to create separate instances for testing.

**Config**: `src/config.ts` loads `.env` and validates with Zod. Required env vars: `DATABASE_URL`, `PORT`, `HOST`.

**Database**: Drizzle ORM with `postgres` (postgres.js) driver.
- `src/db/schema.ts` — all table definitions go here
- `src/db/index.ts` — exports the `db` client with schema attached
- `src/db/migrate.ts` — standalone migration runner
- `drizzle.config.ts` — Drizzle Kit config at project root

**Routes**: `src/routes/` — each file exports an async Fastify plugin function. Register new route files in `src/routes/index.ts`.

**Plugins**: `src/plugins/` — Fastify plugins (error handling, etc). Registered in `app.ts`.

## Conventions

- ESM (`"type": "module"` in package.json) — use `.js` extensions in all imports
- All Drizzle table definitions go in `src/db/schema.ts`
- After modifying the schema, run `pnpm db:generate` then `pnpm db:migrate`