# CLAUDE.md

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

## Project Overview

Banatie is a comprehensive monorepo for AI-powered image generation platform featuring multiple applications:

- **API Service** (`apps/api-service`) - Core REST API using Express.js and TypeScript for image generation with Gemini AI
- **Landing Page** (`apps/landing`) - Next.js public website with demo functionality
- **Studio Platform** (`apps/studio`) - Next.js SaaS application with authentication, billing, and subscriptions. Based on https://github.com/nextjs/saas-starter
- **Admin Dashboard** (`apps/admin`) - Next.js administration interface for monitoring and management

The project uses MinIO for object storage and PostgreSQL for data persistence, all orchestrated with Docker Compose.

## Development Commands

Use `docker compose` command for Docker services (v3 version).

### Infrastructure

- `docker compose up -d postgres minio storage-init` - Start database and storage services
- `docker compose up -d` - Start all services including the API app container
- `docker compose down` - Stop all services

### Monorepo Commands (from root)

- `pnpm dev` - Start all applications in development mode
- `pnpm dev:api` - Start API service only (`apps/api-service`)
- `pnpm dev:landing` - Start landing page only (`apps/landing`)
- `pnpm dev:studio` - Start studio platform only (`apps/studio`)
- `pnpm dev:admin` - Start admin dashboard only (`apps/admin`)

### Build & Production

- `pnpm build` - Build all applications
- `pnpm build:api` - Build API service only
- `pnpm start:api` - Start API service in production mode
- `pnpm start:landing` - Start landing page in production mode

### Code Quality (runs across all apps)

- `pnpm lint` - Run ESLint on all applications
- `pnpm typecheck` - Run TypeScript checking on all applications
- `pnpm test` - Run tests (currently API service only)
- `pnpm clean` - Clean all build outputs and dependencies

## Architecture

### Monorepo Structure

```
banatie-service/
├── apps/
│   ├── api-service/     # Express.js REST API (TypeScript)
│   ├── landing/         # Next.js landing page
│   ├── studio/          # Next.js SaaS platform
│   └── admin/           # Next.js admin dashboard
├── data/                # Docker volume data (postgres, minio)
├── docker-compose.yml   # Infrastructure services
├── pnpm-workspace.yaml  # Workspace configuration
└── package.json         # Root workspace scripts
```

### API Service Architecture (`apps/api-service/`)

- **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
- **Storage**: `src/services/MinioStorageService.ts` handles file uploads to MinIO
- **Route Handling**: `src/routes/generate.ts` contains the main API endpoint logic

### Middleware Stack (API Service)

- `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 (API Service)

- Path aliases configured in `apps/api-service/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/*`

### Storage & Data

- **MinIO**: Object storage for generated images and uploads (port 9000)
- **PostgreSQL**: Database for user data, metadata (port 5434)
- **File Organization**: `orgId/projectId/category/year-month/filename.ext`

## Environment Configuration

### Root Environment (`.env.docker`)

- `MINIO_ROOT_USER` - MinIO admin username
- `MINIO_ROOT_PASSWORD` - MinIO admin password

### API Service Environment (`apps/api-service/.env`)

Required environment variables:

- `GEMINI_API_KEY` - Google Gemini API key (required)
- `MINIO_ENDPOINT` - MinIO endpoint (`localhost:9000` for local dev, `minio:9000` for Docker)
- `MINIO_ACCESS_KEY` - MinIO service account key
- `MINIO_SECRET_KEY` - MinIO service account secret
- `MINIO_BUCKET_NAME` - Storage bucket name (default: `banatie`)
- `PORT` - Server port (default: 3000)
- `NODE_ENV` - Environment mode
- `CORS_ORIGIN` - CORS origin setting (default: \*)

## Key Dependencies

### API Service

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

### Frontend Apps (Next.js)

- **next** - React framework
- **tailwindcss** - Utility-first CSS framework
- **typescript** - Type safety
- **supabase** - Authentication and database (studio app)
- **stripe** - Payment processing (studio app)

## Service Ports

| Service         | Port | Description        |
| --------------- | ---- | ------------------ |
| API Service     | 3000 | REST API endpoints |
| Landing Page    | 3001 | Public website     |
| Studio Platform | 3002 | SaaS application   |
| Admin Dashboard | 3003 | Administration     |
| PostgreSQL      | 5434 | Database           |
| MinIO API       | 9000 | Object storage     |
| MinIO Console   | 9001 | Storage management |

## API Endpoints (API Service)

- `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 workspaces for monorepo management (required >= 8.0.0)
- Node.js >= 18.0.0 required
- TypeScript with strict mode enabled across all apps
- ESLint configured with TypeScript and Prettier integration
- Jest for testing with ts-jest preset (API service)
- Each app can be developed and deployed independently