ci-observer/ci-observer-handover/docs/ARCHITECTURE.md

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

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

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.