93 lines
5.4 KiB
Markdown
93 lines
5.4 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 |
|
||
|
||
### 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 generation |
|
||
| POST | `/generate/video` | ✓ | Text-to-video generation |
|
||
| POST | `/generate/video/from-image` | ✓ | Image-to-video generation |
|
||
|
||
### 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).
|