banatie-service/CLAUDE.md

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