Implement comprehensive live scope management API and IP-based rate limiting
for live URL generation endpoints (Sections 8.5 and 8.6).
**Scope Management CRUD Endpoints:**
- POST /api/v1/live/scopes - Create scope manually with slug validation
- GET /api/v1/live/scopes - List scopes with pagination and stats
- GET /api/v1/live/scopes/:slug - Get single scope by slug with stats
- PUT /api/v1/live/scopes/:slug - Update scope settings
- POST /api/v1/live/scopes/:slug/regenerate - Regenerate scope images
- DELETE /api/v1/live/scopes/:slug - Delete scope with cascading image deletion
**Scope Management Features:**
- Slug format validation (alphanumeric, hyphens, underscores)
- Duplicate slug prevention with 409 Conflict response
- Scope statistics (currentGenerations, lastGeneratedAt)
- Settings management (allowNewGenerations, newGenerationsLimit)
- Regeneration support (single image or all images in scope)
- Hard delete with image cleanup following alias protection rules
- All endpoints require Project Key authentication
**IP-Based Rate Limiting:**
- In-memory rate limit store with automatic cleanup
- Limits: 10 new generations per hour per IP address
- Only cache MISS (new generation) counts toward limit
- Cache HIT does NOT count toward limit
- X-Forwarded-For header support for proxy/load balancer setups
- Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- Retry-After header on 429 Too Many Requests response
- Automatic cleanup of expired entries every 5 minutes
**IP Rate Limiter Middleware:**
- ipRateLimiterMiddleware attaches to live URL endpoint
- getClientIp() extracts IP from X-Forwarded-For or req.ip
- checkIpRateLimit() validates and increments counter
- getRemainingRequests() returns available request count
- getResetTime() returns seconds until reset
- Middleware attaches checkIpRateLimit function to request
- Rate limit check executed AFTER cache check (only for cache MISS)
**Type System Updates:**
- Added LiveScopeResponse interface with all scope fields
- Added LiveScopeWithImagesResponse with images array
- Added response type aliases for all CRUD operations
- Added toLiveScopeResponse() converter function
- Added CreateLiveScopeRequest, UpdateLiveScopeRequest interfaces
- Added ListLiveScopesQuery with pagination parameters
- Added RegenerateScopeRequest with optional imageId
**Route Integration:**
- Mounted scopes router at /api/v1/live/scopes
- Applied ipRateLimiterMiddleware to live URL endpoint
- Rate limit increments only on cache MISS (new generation)
- Cache HIT bypasses rate limit check entirely
**Technical Notes:**
- All scope endpoints return toLiveScopeResponse() format
- Pagination using buildPaginationMeta helper
- Bracket notation for meta field access (TypeScript strict mode)
- Proper number parsing with fallback defaults
- All Phase 3 Part 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 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>
Oleg Proskurin