diff --git a/src/CLAUDE.md b/src/CLAUDE.md
new file mode 100644
index 0000000..c8de246
--- /dev/null
+++ b/src/CLAUDE.md
@@ -0,0 +1,169 @@
+# Magic Building Image Generation Server
+
+## Overview
+
+Express.js server that provides HTTP API endpoints for AI image generation using the Gemini Flash Image model. The server accepts text prompts and optional reference images to generate high-quality images.
+
+## Quick Start
+
+### 1. Environment Setup
+Create a `.env` file in the project root:
+```bash
+GEMINI_API_KEY=your_gemini_api_key_here
+PORT=3000
+CORS_ORIGIN=*
+NODE_ENV=development
+```
+
+### 2. Start the Server
+```bash
+# Development mode with auto-restart
+pnpm server:dev
+
+# Production mode
+pnpm server
+
+# With logging to file
+pnpm server:log
+```
+
+## API Endpoints
+
+### Health Check
+```
+GET /health
+```
+Returns server status and uptime information.
+
+### API Information
+```
+GET /api/info
+```
+Returns API details, available endpoints, and file upload limits.
+
+### Generate Image
+```
+POST /api/generate
+```
+
+**Request Body (multipart/form-data):**
+- `prompt` (string, required): Text description for image generation
+- `filename` (string, optional): Custom filename for the generated image
+- `referenceImages` (files, optional): Up to 3 reference images (5MB max each)
+
+**Supported Image Formats:** PNG, JPEG, JPG, WebP
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "message": "Image generated successfully",
+  "data": {
+    "filename": "generated_image_123.png",
+    "filepath": "./src/results/generated_image_123.png",
+    "description": "Generated image description",
+    "model": "gemini-2.0-flash-exp",
+    "generatedAt": "2024-01-01T12:00:00.000Z"
+  }
+}
+```
+
+## Server Configuration
+
+### File Limits
+- **Max file size**: 5MB per image
+- **Max files**: 3 reference images per request
+- **Request size**: 10MB total request limit
+
+### Output Directory
+Generated images are saved to `./src/results/` by default.
+
+### CORS Settings
+Cross-origin requests are enabled. Configure `CORS_ORIGIN` environment variable to restrict origins in production.
+
+## Usage Examples
+
+### cURL Examples
+
+**Basic text-to-image generation:**
+```bash
+curl -X POST http://localhost:3000/api/generate \
+  -F "prompt=A magical forest with glowing mushrooms" \
+  -F "filename=magical_forest"
+```
+
+**With reference images:**
+```bash
+curl -X POST http://localhost:3000/api/generate \
+  -F "prompt=Character in medieval armor like the reference" \
+  -F "filename=medieval_character" \
+  -F "referenceImages=@path/to/armor_ref.jpg" \
+  -F "referenceImages=@path/to/pose_ref.png"
+```
+
+### JavaScript/Fetch Example
+```javascript
+const formData = new FormData();
+formData.append('prompt', 'A magical crystal cave with blue lighting');
+formData.append('filename', 'crystal_cave');
+
+// Optional: Add reference images
+const fileInput = document.getElementById('imageFile');
+if (fileInput.files[0]) {
+  formData.append('referenceImages', fileInput.files[0]);
+}
+
+const response = await fetch('http://localhost:3000/api/generate', {
+  method: 'POST',
+  body: formData
+});
+
+const result = await response.json();
+console.log(result);
+```
+
+## Error Handling
+
+The server provides detailed error responses:
+
+**Validation Errors (400):**
+- Missing prompt
+- Invalid file formats
+- File size exceeded
+- Too many files
+
+**Server Errors (500):**
+- Missing API key configuration
+- Image generation failures
+- Internal processing errors
+
+**Example Error Response:**
+```json
+{
+  "success": false,
+  "message": "Reference image validation failed",
+  "error": "File size exceeds 5MB limit"
+}
+```
+
+## Development
+
+### Type Checking
+```bash
+pnpm typecheck
+```
+
+### Build
+```bash
+pnpm build
+```
+
+## Architecture
+
+- **Express.js**: Web framework
+- **Multer**: File upload handling
+- **CORS**: Cross-origin resource sharing
+- **Gemini AI**: Image generation service
+- **TypeScript**: Type safety and development experience
+
+The server follows a modular architecture with separate layers for routing, middleware, services, and error handling.
\ No newline at end of file