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>
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>
Oleg Proskurin