ai.allucanget.biz/docs/5-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

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).