ai.allucanget.biz/docs/6-runtime-view.md

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
2. Flask POSTs to POST /generate/image
3. AI Service calls openrouter.ai image model
4. Image URL returned to Flask
5. Flask renders page with generated image

Scenario 4: Video Generation (Text-to-Video)

1. User submits video generation form with prompt and model selection
2. Flask POSTs to POST /generate/video with JWT header
3. Auth Service validates JWT
4. AI Service calls OpenRouter /video/generations
5. OpenRouter returns a job response (status: "queued" or "completed")
6. FastAPI returns VideoResponse to Flask
7. Flask renders result page; if status is queued, the UI may poll or notify asynchronously

Scenario 5: Image-to-Video Generation

1. User uploads or provides an image URL and a text prompt
2. Flask POSTs to POST /generate/video/from-image with JWT header
3. AI Service calls OpenRouter /video/generations/from-image
4. Returns VideoResponse with video_url when completed

Scenario 6: 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 7: 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