From 9b0b74f6863ba58d2498d36c123eb0aa8bb1c220 Mon Sep 17 00:00:00 2001 From: Oleg Proskurin Date: Mon, 29 Sep 2025 22:53:44 +0700 Subject: [PATCH] chore: update docs --- CLAUDE.md | 132 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 103 insertions(+), 29 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 256c118..5cbea39 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,44 +4,81 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 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. +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 using docker-compose service (v3 version) +Use `docker compose` command for Docker services (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 +### Infrastructure -### 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 +- `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 -### Testing -- `pnpm test` - Run Jest tests -- `pnpm test:watch` - Run tests in watch mode -- `pnpm test:coverage` - Run tests with coverage report +### 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 -### Core Structure +### 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 +### 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 -- Path aliases configured in tsconfig.json: +### 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/*` @@ -49,30 +86,66 @@ use `docker compose` command for using docker-compose service (v3 version) - `@/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` +### 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: *) +- `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 -## API Endpoints +### 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 @@ -80,8 +153,9 @@ Required environment variables: ## Development Notes -- Uses pnpm as package manager (required >= 8.0.0) +- Uses pnpm workspaces for monorepo management (required >= 8.0.0) - Node.js >= 18.0.0 required -- TypeScript with strict mode enabled +- TypeScript with strict mode enabled across all apps - ESLint configured with TypeScript and Prettier integration -- Jest for testing with ts-jest preset \ No newline at end of file +- Jest for testing with ts-jest preset (API service) +- Each app can be developed and deployed independently