eyrun-api/CLAUDE.md

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

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