chore: update docs
This commit is contained in:
parent
f572428a87
commit
9b0b74f686
132
CLAUDE.md
132
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
|
||||
- Jest for testing with ts-jest preset (API service)
|
||||
- Each app can be developed and deployed independently
|
||||
|
|
|
|||
Loading…
Reference in New Issue