ai.allucanget.biz/docs/05-building-block-view.md

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

┌────────────────────────┐
│  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).