88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# 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
|