Implement cached generation endpoint that streams image bytes directly with
intelligent caching based on prompt hashing for optimal performance.
**Core Service:**
- **PromptCacheService**: Prompt-based cache management
- SHA-256 hashing of prompts for cache lookup
- Cache hit/miss tracking with statistics
- Support for cache entry creation and retrieval
- Hit count and last accessed timestamp tracking
- Cache statistics per project
**v1 API Routes:**
- `GET /api/v1/live/generate` - Generate with caching, stream image bytes
**Endpoint Features:**
- Prompt-based caching with SHA-256 hashing
- Cache HIT: Streams existing image with X-Cache-Status: HIT header
- Cache MISS: Generates new image, caches it, streams with X-Cache-Status: MISS
- Direct image byte streaming (not JSON response)
- Cache-Control headers for browser caching (1 year max-age)
- Hit count tracking for cache analytics
- Integration with promptUrlCache database table
**Caching Logic:**
- Compute SHA-256 hash of prompt for cache key
- Check cache by promptHash and projectId
- On HIT: Fetch image from database, download from storage, stream bytes
- On MISS: Generate new image, create cache entry, stream bytes
- Record cache hits with incremented hit count
**Response Headers:**
- Content-Type: image/jpeg (or appropriate MIME type)
- Content-Length: Actual byte length
- Cache-Control: public, max-age=31536000 (1 year)
- X-Cache-Status: HIT | MISS
- X-Cache-Hit-Count: Number of cache hits (on HIT)
- X-Generation-Id: UUID (on MISS)
- X-Image-Id: UUID (always)
**Technical Notes:**
- Uses ImageService to fetch cached images by ID
- Uses StorageFactory to download image buffers from MinIO
- Parses storage keys to extract org/project/category/filename
- Validates storage key format before download
- All Phase 5 code is fully type-safe with zero TypeScript errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement complete image management system with file upload, listing, retrieval,
updates, alias assignment, and soft deletion.
**v1 API Routes:**
- `POST /api/v1/images/upload` - Upload single image file with database record
- `GET /api/v1/images` - List images with filters and pagination
- `GET /api/v1/images/:id` - Get single image by ID
- `PUT /api/v1/images/:id` - Update image metadata (alias, focal point, meta)
- `PUT /api/v1/images/:id/alias` - Assign project-scoped alias to image
- `DELETE /api/v1/images/:id` - Soft delete image
**Upload Endpoint Features:**
- Uses uploadSingleImage middleware for file handling
- Creates database record with image metadata
- Stores file in MinIO storage (uploads category)
- Supports optional alias and flowId parameters
- Returns ImageResponse with all metadata
**Route Features:**
- Authentication via validateApiKey middleware
- Project key requirement
- Rate limiting on upload endpoint
- Request validation with pagination
- Error handling with proper status codes
- Response transformation with toImageResponse converter
- Project ownership verification for all operations
**ImageService Integration:**
- Uses existing ImageService methods
- Supports filtering by flowId, source, alias
- Soft delete with deletedAt timestamp
- Alias validation and conflict detection
**Type Updates:**
- Updated ImageFilters with explicit | undefined for optional properties
- All response types already defined in responses.ts
**Technical Notes:**
- Upload creates both storage record and database entry atomically
- Focal point stored as JSON with x/y coordinates
- Meta field for flexible metadata storage
- File hash set to null (TODO: implement hashing)
- All Phase 4 code is fully type-safe with zero TypeScript errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement complete flow management system with CRUD operations, computed counts,
and alias management capabilities for organizing generation chains.
**Core Service:**
- **FlowService**: Complete flow lifecycle management
- Create flows with initial empty aliases
- CRUD operations (create, read, update, delete)
- Computed counts for generations and images per flow
- Alias management (add, update, remove)
- Get flow's generations and images with pagination
- No soft delete (flows use hard delete)
**v1 API Routes:**
- `POST /api/v1/flows` - Create new flow
- `GET /api/v1/flows` - List flows with pagination and counts
- `GET /api/v1/flows/:id` - Get single flow with computed counts
- `GET /api/v1/flows/:id/generations` - List flow's generations
- `GET /api/v1/flows/:id/images` - List flow's images
- `PUT /api/v1/flows/:id/aliases` - Update flow aliases (add/modify)
- `DELETE /api/v1/flows/:id/aliases/:alias` - Remove specific alias
- `DELETE /api/v1/flows/:id` - Delete flow (hard delete)
**Route Features:**
- Authentication via validateApiKey middleware
- Project key requirement
- Request validation with pagination
- Error handling with proper status codes
- Response transformation with toFlowResponse converter
- Project ownership verification for all operations
**Type Updates:**
- Added ListFlowGenerationsResponse and ListFlowImagesResponse
- Updated GetFlowResponse to return FlowResponse (not FlowWithDetailsResponse)
- FlowService methods return FlowWithCounts where appropriate
**Technical Notes:**
- Flows don't have deletedAt column (no soft delete support)
- All count queries filter active generations/images only
- Alias updates are merged with existing aliases
- Empty flows return generationCount: 0, imageCount: 0
- All Phase 3 code is fully type-safe with zero TypeScript errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement the complete image generation lifecycle with ImageService, GenerationService,
and v1 API endpoints. This enables end-to-end generation with alias support and flow management.
**Core Services:**
- **ImageService**: Full CRUD for images table
- Create/read/update/delete operations
- Soft delete support with deletedAt
- Project and flow alias assignment
- Storage key and file hash tracking
- Pagination and filtering
- **GenerationService**: Complete generation lifecycle orchestration
- Create generation records with pending status
- Resolve reference images via AliasService
- Call ImageGenService for AI generation
- Create image records in database
- Link images to generations
- Update generation status (processing → success/failed)
- Support for flow association and alias assignment
- Retry failed generations
- Soft/hard delete operations
**v1 API Routes:**
- `POST /api/v1/generations` - Create with references & aliases
- `GET /api/v1/generations` - List with filters & pagination
- `GET /api/v1/generations/:id` - Get with full relations
- `POST /api/v1/generations/:id/retry` - Retry failed generation
- `DELETE /api/v1/generations/:id` - Delete generation & output
**Route Features:**
- Authentication via validateApiKey middleware
- Project key requirement
- Rate limiting per API key
- Request validation with pagination
- Error handling with proper status codes
- Response transformation with type converters
**Type Updates:**
- Add explicit undefined to optional properties for exactOptionalPropertyTypes
- CreateGenerationParams interface for service layer
- GenerationFilters with proper optionals
**Infrastructure:**
- Mount v1Router at /api/v1 in app.ts
- Keep legacy routes for backward compatibility
- Versioned API structure for future iterations
**Technical Notes:**
- Reference image download temporarily skipped (TODO: storage key parsing)
- File hash computation temporarily disabled (TODO: helper method)
- File size set to 0 (TODO: get from storage)
- All Phase 2 code is fully type-safe with zero TypeScript errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement foundational components for Banatie API v2.0 with dual alias system,
flows support, and comprehensive type safety.
**Type Definitions:**
- Add models.ts with database types (Generation, Image, Flow, etc.)
- Add requests.ts with all v2 API request types
- Add responses.ts with standardized response types and converters
- Support for pagination, filters, and complex relations
**Constants:**
- Define technical aliases (@last, @first, @upload)
- Define reserved aliases and validation patterns
- Add rate limits for master/project keys (2-bucket system)
- Add pagination, image, generation, and flow limits
- Comprehensive error messages and codes
**Validators:**
- aliasValidator: Format validation, reserved alias checking
- paginationValidator: Bounds checking with normalization
- queryValidator: UUID, aspect ratio, focal point, date range validation
**Helpers:**
- paginationBuilder: Standardized pagination response construction
- hashHelper: SHA-256 utilities for caching and file deduplication
- queryHelper: Reusable WHERE clause builders with soft delete support
**Core Services:**
- AliasService: 3-tier alias resolution (technical → flow → project)
- Technical alias computation (@last, @first, @upload)
- Flow-scoped alias lookup from JSONB
- Project-scoped alias lookup with uniqueness
- Conflict detection and validation
- Batch resolution support
**Dependencies:**
- Add drizzle-orm to api-service for direct ORM usage
All Phase 1 code is type-safe with zero TypeScript errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Oleg Proskurin