# 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`.