111 lines
8.7 KiB
Markdown
111 lines
8.7 KiB
Markdown
# 5. Building Block View
|
||
|
||
Static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, …) as well as their dependencies (relationships, associations, …).
|
||
|
||
## Level 1 – Whitebox Overall System
|
||
|
||
```text
|
||
┌────────────────────────┐
|
||
│ Frontend (Flask) │
|
||
└───────┬────────────────┘
|
||
│ REST API calls
|
||
┌───────▼────────────────┐
|
||
│ FastAPI Backend │
|
||
│ ├─ Auth Service │
|
||
│ ├─ User Service │
|
||
│ ├─ AI Service │
|
||
│ └─ DB Service (DuckDB)│
|
||
└───────┬────────────────┘
|
||
│ DB access
|
||
┌───────▼────────────────┐
|
||
│ DuckDB Database │
|
||
└────────────────────────┘
|
||
```
|
||
|
||
**Motivation:** Separating the UI (Flask) from the API (FastAPI) allows independent scaling and testing of each layer.
|
||
|
||
**Contained Building Blocks:**
|
||
|
||
| Name | Responsibility |
|
||
| ---------------- | -------------------------------------------------- |
|
||
| Frontend (Flask) | Serves HTML/CSS/JS UI, proxies requests to FastAPI |
|
||
| FastAPI Backend | Handles auth, user management, AI generation API |
|
||
| Auth Service | JWT issuance and validation |
|
||
| User Service | CRUD operations for user accounts |
|
||
| AI Service | Sends prompts to openrouter.ai, returns results |
|
||
| DB Service | Reads/writes to DuckDB |
|
||
| DuckDB Database | Persistent storage for users and session data |
|
||
|
||
## Level 2 – FastAPI Backend internals
|
||
|
||
### White Box Auth Service (`/auth`)
|
||
|
||
Handles JWT issuance, validation, and refresh token lifecycle.
|
||
|
||
| Method | Path | Auth required | Description |
|
||
| ------ | ---------------- | :-----------: | ------------------------------------------------ |
|
||
| POST | `/auth/register` | — | Create a new user account |
|
||
| POST | `/auth/login` | — | Authenticate and receive access + refresh tokens |
|
||
| POST | `/auth/refresh` | — | Rotate refresh token, get a new access token |
|
||
| POST | `/auth/logout` | — | Revoke refresh token |
|
||
|
||
### White Box User Service (`/users`)
|
||
|
||
Self-service profile management and admin user CRUD.
|
||
|
||
| Method | Path | Auth required | Admin only | Description |
|
||
| ------ | ------------------ | ------------- | ---------- | ---------------------------------------- |
|
||
| GET | `/users/me` | ✓ | — | Get current user profile |
|
||
| PUT | `/users/me` | ✓ | — | Update own email or password |
|
||
| GET | `/users` | ✓ | ✓ | List all users |
|
||
| DELETE | `/users/{id}` | ✓ | ✓ | Delete a user (cannot self-delete) |
|
||
| PUT | `/users/{id}/role` | ✓ | ✓ | Change a user's role (`user` \| `admin`) |
|
||
|
||
### White Box Admin Service (`/admin`)
|
||
|
||
Operational endpoints for application management.
|
||
|
||
| Method | Path | Auth required | Admin only | Description |
|
||
| ------ | --------------------------- | ------------- | ---------- | ------------------------------------------ |
|
||
| GET | `/admin/stats` | ✓ | ✓ | User counts by role, token activity |
|
||
| GET | `/admin/health/db` | ✓ | ✓ | DuckDB connectivity check |
|
||
| POST | `/admin/tokens/purge` | ✓ | ✓ | Remove expired/revoked refresh tokens |
|
||
| GET | `/admin/videos` | ✓ | ✓ | List all video jobs with user emails |
|
||
| POST | `/admin/videos/{id}/cancel` | ✓ | ✓ | Cancel a queued/processing video job |
|
||
| POST | `/admin/videos/{id}/retry` | ✓ | ✓ | Retry a failed/cancelled video job |
|
||
| DELETE | `/admin/videos/{id}` | ✓ | ✓ | Permanently delete a video job |
|
||
| POST | `/admin/videos/purge` | ✓ | ✓ | Delete old completed/failed/cancelled jobs |
|
||
| POST | `/admin/videos/timed-out` | ✓ | ✓ | Mark stale processing jobs as failed |
|
||
| GET | `/admin/models` | ✓ | ✓ | List cached OpenRouter models |
|
||
| POST | `/admin/models/refresh` | ✓ | ✓ | Refresh model cache from OpenRouter |
|
||
|
||
### White Box AI Service (`/ai`, `/generate`)
|
||
|
||
Model listing and multi-modal generation via openrouter.ai.
|
||
|
||
| Method | Path | Auth required | Description |
|
||
| ------ | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/ai/models` | ✓ | List available OpenRouter models |
|
||
| POST | `/ai/chat` | ✓ | Multi-turn chat completion |
|
||
| POST | `/generate/text` | ✓ | Single-prompt text generation (optional system prompt) |
|
||
| POST | `/generate/image` | ✓ | Text-to-image (DALL-E via `/images/generations` or FLUX/GPT-5 Image Mini via `/chat/completions` with `modalities`) |
|
||
| POST | `/generate/video` | ✓ | Text-to-video (Sora 2 Pro, Veo 3.1 Fast) — returns `polling_url` |
|
||
| POST | `/generate/video/from-image` | ✓ | Image-to-video — returns `polling_url` |
|
||
| GET | `/generate/video/status` | ✓ | Poll video generation status via `polling_url` |
|
||
| GET | `/generate/images` | ✓ | List current user's generated images |
|
||
| GET | `/generate/images/{id}` | ✓ | Get a single generated image |
|
||
| GET | `/generate/videos` | ✓ | List current user's video jobs |
|
||
| GET | `/generate/videos/{id}` | ✓ | Get a single video job |
|
||
| POST | `/generate/videos/{id}/cancel` | ✓ | Cancel a queued/processing video job |
|
||
|
||
**Video generation flow:** The `/generate/video` and `/generate/video/from-image` endpoints queue a job in the local database and return immediately with `status: "queued"`. A background worker (`video_worker.py`) submits the job to OpenRouter's `/api/v1/videos` endpoint, receives a `polling_url`, and polls it periodically until the job reaches `"completed"` or `"failed"`. The frontend polls `GET /generate/video/{id}/status` every 5 seconds to show live status updates.
|
||
|
||
**Image generation routing:** The router auto-detects the model type — models containing `"flux"` or `"gpt-5-image-mini"` are routed to `/chat/completions` with `modalities: ["image"]` (or `["image", "text"]` depending on cached output modalities), while others (e.g. DALL-E 3) use the legacy `/images/generations` endpoint.
|
||
|
||
### White Box DB Service (`db.py`)
|
||
|
||
- Singleton DuckDB connection, opened on FastAPI startup via lifespan hook.
|
||
- `asyncio.Lock` serialises all write operations within the single process.
|
||
- Schema migration runs automatically on first startup.
|
||
- Tables: `users`, `refresh_tokens` (see Section 8 for schema details).
|