87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
# 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
|
|
|
|
use `docker compose` command for using docker-compose service (v3 version)
|
|
|
|
### 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 |