ai.allucanget.biz/docs/06-runtime-view.md

6. Runtime View

Describes concrete behavior and interactions of the system's building blocks in form of scenarios from the following areas:

• Important use cases or features: how do building blocks execute them?
• Interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?
• Operation and administration: launch, start-up, stop
• Error and exception scenarios

Scenario 1: User Authentication

1. User submits login form in Flask frontend
2. Flask POSTs credentials to POST /auth/login
3. Auth Service validates credentials against DuckDB
4. Auth Service returns JWT token
5. Flask stores token in session cookie
6. User is redirected to dashboard

Scenario 2: AI Text Generation

1. User fills in text generation form in Flask frontend
2. Flask POSTs prompt + model to POST /generate/text with JWT header
3. Auth Service validates JWT
4. AI Service sends prompt to openrouter.ai
5. openrouter.ai returns generated text
6. FastAPI returns result to Flask
7. Flask renders result page for user

Scenario 3: Image Generation

1. User submits image generation form with prompt, model, size, aspect ratio, and resolution
2. Flask POSTs to POST /generate/image with JWT header
3. Router auto-detects model type:
   • FLUX / GPT-5 Image Mini: calls /chat/completions with modalities: ["image"] and image_config
   • DALL-E 3: calls /images/generations with size and n
4. Image URL (base64 data URL or hosted URL) returned to Flask
5. Flask renders page with generated image(s)

Scenario 3a: Image Generation with Aspect Ratio & Resolution

1. User selects aspect ratio (e.g. 16:9) and resolution (2K) on the image generation form
2. Flask POSTs aspect_ratio and image_size to POST /generate/image
3. Backend passes these as image_config to the chat completions endpoint (for FLUX/GPT-5 Image Mini)
4. Generated image respects the requested aspect ratio and resolution

Scenario 4: Video Generation (Text-to-Video)

1. User submits video generation form with prompt, model, aspect ratio, resolution, and duration
2. Flask POSTs to POST /generate/video with JWT header
3. Auth Service validates JWT
4. Backend inserts a row into generated_videos with status: "queued" and returns the DB job ID
5. Flask renders result page with polling UI
6. Background worker (video_worker.py) picks up queued jobs every 15 seconds:
   • Calls OpenRouter POST /api/v1/videos with model, prompt, and parameters
   • Receives {"id": "...", "polling_url": "..."} and updates the DB row to status: "processing"
   • Polls the polling_url every 15 seconds until status is "completed" or "failed"
   • Updates the DB row with the final status and video URL
7. Frontend JavaScript polls GET /generate/video/{db_id}/status every 5 seconds
8. When status becomes "completed", the response includes video_url — the video is displayed in a <video> element
9. If status becomes "failed", an error message is shown
10. User can click "Cancel Job" to mark the job as "cancelled" (stops local polling, does not stop the provider job)

Scenario 4a: Video Generation (Image-to-Video)

1. User provides an image URL, motion prompt, model, aspect ratio, resolution, and duration
2. Flask POSTs to POST /generate/video/from-image with JWT header
3. Same background worker flow as Scenario 4, with generation_type: "image_to_video"

Scenario 4b: Video Job Cancellation

1. User clicks "Cancel Job" on the video detail page or gallery pending card
2. Frontend POSTs to /generate/video/{id}/cancel
3. Backend verifies the job belongs to the user and is not in a terminal state
4. Backend updates the DB row status to "cancelled"
5. Frontend stops polling and updates the UI to show "Job cancelled"

Scenario 5: Token Refresh

1. Access token expires (TTL 15 min)
2. Client POSTs current refresh token to POST /auth/refresh
3. Auth Service validates JTI against refresh_tokens table (not revoked, not expired)
4. Old JTI is revoked; new JTI inserted into refresh_tokens
5. New access token + new refresh token returned to client

Scenario 6: Admin User Management

1. Admin logs in and receives access token with role: admin
2. Admin GETs /admin/stats to view user and token counts
3. Admin DELETEs /users/{id} to remove a user — refresh tokens for that user are cascade-deleted
4. Admin PUTs /users/{id}/role to promote a user to admin or demote to user

Scenario 7: User Profile Update

1. Authenticated user navigates to /users/profile
2. User submits updated email and/or new password
3. Flask POSTs to PUT /users/me with JWT header
4. Auth Service validates credentials and updates user record in DuckDB
5. Session user_email is updated; user sees success message