# CLAUDE.md

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

## Project Overview

Banatie is a REST API service for AI-powered image generation using the Gemini Flash Image model. It's built with Express.js and TypeScript, providing endpoints to generate images from text prompts with optional reference images.

## Development Commands

### Core Development
- `pnpm dev` - Start development server with auto-reload using tsx
- `pnpm start` - Start production server (runs build first)
- `pnpm build` - Build TypeScript to JavaScript in ./dist
- `pnpm typecheck` - Run TypeScript type checking without emitting files

### Code Quality
- `pnpm lint` - Run ESLint on all TypeScript files in src/
- `pnpm lint:fix` - Run ESLint with auto-fix
- `pnpm format` - Format code with Prettier
- `pnpm format:check` - Check if code is formatted correctly

### Testing
- `pnpm test` - Run Jest tests
- `pnpm test:watch` - Run tests in watch mode
- `pnpm test:coverage` - Run tests with coverage report

## Architecture

### Core Structure
- **Express App**: Configured in `src/app.ts` with middleware, CORS, and route mounting
- **Server Entry**: `src/server.ts` starts the HTTP server
- **Image Generation**: `src/services/ImageGenService.ts` handles Gemini AI integration
- **Route Handling**: `src/routes/generate.ts` contains the main API endpoint logic

### Middleware Stack
- `src/middleware/upload.ts` - Multer configuration for file uploads (max 3 files, 5MB each)
- `src/middleware/validation.ts` - Express-validator for request validation
- `src/middleware/errorHandler.ts` - Centralized error handling and 404 responses

### TypeScript Configuration
- Path aliases configured in tsconfig.json:
  - `@/*` maps to `src/*`
  - `@/types/*` maps to `src/types/*`
  - `@/services/*` maps to `src/services/*`
  - `@/middleware/*` maps to `src/middleware/*`
  - `@/routes/*` maps to `src/routes/*`
  - `@/utils/*` maps to `src/utils/*`

### File Handling
- **Uploads**: Temporary files stored in `./uploads/temp`
- **Results**: Generated images saved to `./results`
- **Logs**: Application logs in `./logs`

## Environment Configuration

Required environment variables:
- `GEMINI_API_KEY` - Google Gemini API key (required)
- `PORT` - Server port (default: 3000)
- `NODE_ENV` - Environment mode
- `CORS_ORIGIN` - CORS origin setting (default: *)

## Key Dependencies

- **@google/genai** - Google Gemini AI client
- **express** v5 - Web framework
- **multer** - File upload handling
- **express-validator** - Request validation
- **winston** - Logging
- **helmet** - Security middleware
- **express-rate-limit** - Rate limiting

## API Endpoints

- `GET /health` - Health check with uptime and status
- `GET /api/info` - API information and limits
- `POST /api/generate` - Main image generation endpoint (multipart/form-data)

## Development Notes

- Uses pnpm as package manager (required >= 8.0.0)
- Node.js >= 18.0.0 required
- TypeScript with strict mode enabled
- ESLint configured with TypeScript and Prettier integration
- Jest for testing with ts-jest preset