add architecture documentation and testing strategy

Co-authored-by: Copilot <copilot@github.com>

docs/6-runtime-view.md

@@ -0,0 +1,67 @@
+# 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