Oleg Proskurin
a92b1bf482
Add complete JSDoc documentation to all API v1 endpoints with detailed descriptions, parameters, returns, error codes, and usage examples (Section 12). **Generation Endpoints (generations.ts):** - POST / - Create generation with references, aliases, and enhancement - GET / - List with flow/status filtering and pagination - GET /:id - Get single generation with full relations - PUT /:id - Update with auto-regeneration on prompt/aspectRatio change - POST /:id/regenerate - Regenerate with exact same parameters - POST /:id/retry - Legacy endpoint (deprecated, delegates to regenerate) - DELETE /:id - Delete with alias protection rules **Flow Endpoints (flows.ts):** - GET / - List flows with computed counts and pagination - GET /:id - Get single flow with generationCount and imageCount - GET /:id/generations - List flow's generations with pagination - GET /:id/images - List flow's images with pagination - PUT /:id/aliases - Update flow-scoped aliases (JSONB merge) - DELETE /:id/aliases/:alias - Remove specific flow alias - POST /:id/regenerate - Regenerate most recent generation in flow - DELETE /:id - Hard delete flow (generations/images remain) **Image Endpoints (images.ts):** - POST /upload - Upload with flowId logic (undefined=auto, null=none, string=specific) - GET / - List with flow/source/alias filtering and pagination - GET /resolve/:alias - 3-tier resolution (technical → flow → project) - GET /:id - Get single image with complete details - PUT /:id - Update focal point and metadata - PUT /:id/alias - Assign project-scoped alias (Section 6.1) - DELETE /:id - Hard delete with MinIO cleanup and cascades **CDN Endpoints (cdn.ts):** - GET /:orgSlug/:projectSlug/img/:filenameOrAlias - Public image serving - Supports filename and @alias access - Long-term browser caching (1 year) - No authentication required - GET /:orgSlug/:projectSlug/live/:scope - Live URL generation - Automatic prompt-based caching - IP rate limiting (10/hour, cache hits excluded) - Lazy scope creation - Scope generation limits - Cache key from prompt + params - X-Cache-Status: HIT|MISS headers **Scope Management Endpoints (scopes.ts):** - POST / - Create scope manually with settings - GET / - List with currentGenerations stats and pagination - GET /:slug - Get single scope by slug with stats - PUT /:slug - Update settings (allowNewGenerations, limits) - POST /:slug/regenerate - Regenerate specific image or all in scope - DELETE /:slug - Delete scope with cascading image deletion **JSDoc Standards Applied:** - Complete function descriptions with use cases - @route method and path - @authentication requirements and key types - @rateLimit specifications where applicable - @param detailed parameter descriptions with types and optionality - @returns status codes with response descriptions - @throws error codes with explanations - @example realistic usage examples with request/response samples - @deprecated tags for legacy endpoints **Documentation Features:** - Comprehensive parameter descriptions - Default values clearly indicated - Type information for all parameters - Error code documentation - Multiple examples per complex endpoint - Response header documentation - Cache behavior explanations - Flow logic documentation - Alias resolution precedence details - Rate limiting specifics All JSDoc follows standardized format for consistent API documentation across the entire v1 API surface. Zero new TypeScript errors introduced. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> |
||
|---|---|---|
| .claude | ||
| apps | ||
| docs | ||
| packages/database | ||
| prod-env | ||
| scripts | ||
| tests | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| .mcp.json | ||
| .prettierignore | ||
| .prettierrc.json | ||
| CLAUDE.md | ||
| README.md | ||
| UPLOAD_COMPONENTS_DELIVERY.md | ||
| UPLOAD_PAGE_IMPLEMENTATION.md | ||
| api-refactoring-final.md | ||
| banatie-api-requirements.md | ||
| banatie-database-design.md | ||
| banatie.code-workspace | ||
| demo.test.ts | ||
| infrastructure.md | ||
| minio-setup.md | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| test-api.sh | ||
| test-filename-sanitization.js | ||
| vitest.config.ts | ||
README.md
Banatie - AI Image Generation Service
A comprehensive monorepo for the Banatie AI image generation platform, featuring multiple applications for different use cases.
Architecture Overview
banatie-service/
├── apps/
│ ├── api-service/ # REST API for image generation (Express.js + TypeScript)
│ ├── landing/ # Landing page with demo (Next.js)
│ ├── studio/ # SaaS platform with billing (Next.js + Supabase + Stripe)
│ └── admin/ # Administration dashboard (Next.js)
├── data/ # Docker volumes (postgres, minio)
├── docker-compose.yml # Infrastructure services
└── package.json # Workspace scripts
Applications
🚀 API Service (apps/api-service)
- Port: 3000
- Tech: Express.js, TypeScript, Gemini AI
- Purpose: Core REST API for AI image generation
- Features: Image generation, file upload, rate limiting, logging
🌐 Landing Page (apps/landing)
- Port: 3001
- Tech: Next.js 14, Tailwind CSS
- Purpose: Public landing page with demo
- Features: Service overview, image generation demo
🏢 Studio (apps/studio)
- Port: 3002
- Tech: Next.js 14, Supabase, Stripe
- Purpose: SaaS platform for paid users
- Features: Authentication, billing, subscriptions, usage tracking
🔧 Admin (apps/admin)
- Port: 3003
- Tech: Next.js 14, Dashboard components
- Purpose: Service administration and monitoring
- Features: System monitoring, user management, analytics
Quick Start
Prerequisites
- Node.js >= 18.0.0
- pnpm >= 8.0.0
- Docker & Docker Compose
Development Setup
# Clone and install dependencies
git clone <repository-url>
cd banatie-service
pnpm install
# Start infrastructure (PostgreSQL + MinIO)
docker compose up -d postgres minio storage-init
# Start all applications in development mode
pnpm dev
# Or start individual apps
pnpm dev:api # API Service on :3000
pnpm dev:landing # Landing Page on :3001
pnpm dev:studio # Studio Platform on :3002
pnpm dev:admin # Admin Dashboard on :3003
Production Deployment
# Build all applications
pnpm build
# Start infrastructure
docker compose up -d
# Start production servers
pnpm start:api
pnpm start:landing
pnpm start:studio
pnpm start:admin
Development Commands
# Install dependencies for all apps
pnpm install
# Development (all apps in parallel)
pnpm dev
# Build all apps
pnpm build
# Type checking
pnpm typecheck
# Linting
pnpm lint
# Testing (API service only)
pnpm test
# Clean all build outputs
pnpm clean
Environment Configuration
Each application has its own environment configuration:
- Root:
.env.docker(for Docker services) - API Service:
apps/api-service/.env - Studio:
apps/studio/.env.local - Admin:
apps/admin/.env.local
See individual app README files for specific environment variables.
Services & Ports
| Service | Port | Description |
|---|---|---|
| API Service | 3000 | Core REST API |
| Landing Page | 3001 | Public website |
| Studio Platform | 3002 | SaaS application |
| Admin Dashboard | 3003 | Administration |
| PostgreSQL | 5460 | Database |
| MinIO API | 9000 | Object storage |
| MinIO Console | 9001 | Storage admin |
API Usage
Generate Image
# Text-to-image
curl -X POST http://localhost:3000/api/text-to-image \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"prompt": "A magical forest with glowing mushrooms",
"filename": "magical_forest"
}'
See apps/api-service/README.md for detailed API documentation.
Contributing
- Each app has its own package.json and dependencies
- Use the root workspace commands for multi-app operations
- Follow the existing code style and patterns
- Run
pnpm typecheckandpnpm lintbefore committing
License
MIT License - see individual app directories for more details.