usulpro
/
banatie-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
banatie-service/CLAUDE.md

6.0 KiB
Raw Blame History

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