diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ca66458
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,85 @@
+# 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
\ No newline at end of file