# 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