ai.allucanget.biz/docs/6-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 calls OpenRouter POST /api/v1/videos with model, prompt, aspect_ratio, resolution, duration_seconds
5. OpenRouter returns {"id": "...", "polling_url": "..."} with status: "queued"
6. FastAPI returns VideoResponse with polling_url to Flask
7. Flask renders result page with polling UI
8. Frontend JavaScript polls GET /generate/video/status?polling_url=... every 5 seconds
9. When status becomes "completed", the response includes unsigned_urls — the video is displayed in a <video> element
10. If status becomes "failed", an error message is shown

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. Backend calls OpenRouter POST /api/v1/videos with image_url, prompt, and parameters
4. Same polling flow as Scenario 4

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