feat: initial commit

ci-observer-handover/docs/ARCHITECTURE.md

@@ -0,0 +1,72 @@
+# CI Observer Architecture
+
+## What It Is
+CI Observer is a read-only dashboard that polls GitHub Actions run data and renders a live CI status wall.
+
+## Core Technologies
+- Backend: Python 3.11 + FastAPI
+- HTTP client: `httpx`
+- Storage: SQLite (`/app/data/ci_observer.db`)
+- Frontend: server-rendered static HTML/CSS/JS (no SPA framework)
+- Runtime: Docker + Docker Compose
+- Source control: GitHub
+
+## High-Level Flow
+```mermaid
+flowchart LR
+    GH[GitHub Actions API] -->|poll runs| APP[FastAPI Poller]
+    APP -->|upsert| DB[(SQLite)]
+    UI[Browser] -->|GET /api/runs /api/filters /api/config| APP
+    APP -->|query| DB
+    APP -->|JSON + static assets| UI
+```
+
+## Runtime Components
+```mermaid
+flowchart TB
+    subgraph Runner_VM
+      C[Docker Container: ci-observer-dashboard-prod]
+      D[(Volume ./data -> /app/data)]
+      S[Static UI: index.html + app.js + styles.css]
+      A[FastAPI app/main.py]
+      C --> A
+      C --> S
+      C --> D
+    end
+
+    Browser -->|HTTP :8089| C
+    A -->|HTTPS calls| GitHubAPI[api.github.com]
+```
+
+## Data Model (Main Fields)
+Stored run fields include:
+- `repo`, `workflow`, `run_id`, `status`, `conclusion`
+- `head_branch`, `head_sha`, `actor`
+- `started_at`, `updated_at`, `duration_seconds`
+- `html_url`
+- `raw_json` (full run payload for future extensions)
+
+## App Principles
+- Read-only by design: no write-back to GitHub or pipeline control.
+- Operational simplicity: one container, one DB file, one compose file per instance.
+- Clear rollout model: feature branch on test port, then merge to `main`, then production deploy.
+- Low blast radius: test instances isolated by folder, port, and SQLite volume path.
+
+## Config Contract
+Environment variables:
+- `GITHUB_TOKEN`
+- `GH_REPOS` (comma-separated)
+- `GH_WORKFLOWS` (comma-separated workflow file names)
+- `REFRESH_SECONDS`
+- `DASHBOARD_TITLE`
+
+Important:
+- Current polling logic requires both `GH_REPOS` and `GH_WORKFLOWS`.
+- If `GH_WORKFLOWS` is empty, polling does not start.
+
+## Deployment Model Used
+1. Build/test on temporary instance in `/webapps/ci-observer-dashboard-<feature>` on test port.
+2. Validate UI/behavior.
+3. Merge approved branch to `main`.
+4. Production update from `/webapps/ci-observer-dashboard-prod` on `8089`.
+