# dashboard.pdhc — Technical Description

## Purpose
Read-only visualisation dashboard over observations delivered to gateway.pdhc
from upstream providers. Serves an eligible-patient list, cohort time-activity
curves, and a per-patient dashboard. Part of the PDHC microservice suite.

## Architecture
```
[provider.pdhc] ── push ──► [gateway.pdhc] ◄── GET Observation ── [dashboard.pdhc]
                                                                        │
                                                                 Postgres (9026)
                                                                        │
                                                                   Flask (9027)
```

- **Rule 6**: dashboard relies on gateway.pdhc for all observation data.
- **Rule 5 / 10**: own Postgres on localhost (`dashboard_pdhc_db`, port 9026).
- **Rule 16**: ports 9026–9029 reserved. 9026=DB, 9027=Flask app.
- **Rule 18**: every internal reference is by GUID.
- **Rule 24**: admins see all orgs; members restricted to their OrgMembership rows.

## Components
- `app/__init__.py` — Flask app factory, config, logging to `results/<ts>/app.log`.
- `app/models/__init__.py` — SQLAlchemy models: `User`, `OrgMembership`,
  `ObservationCache`, `RefreshLog`.
- `app/auth.py` — `AUTH_MODE=off` bypass (dev SU), SSO stub, `scope_to_user_orgs`
  helper, `flask create-su` CLI (Rule 23).
- `app/services/gateway_client.py` — `GatewayClient.fetch_observations()` calls
  `GET {GATEWAY_BASE_URL}/fhir/Observation?organization=<org>`; `normalise()`
  maps FHIR Observation → `ObservationCache` shape; `refresh_org()` is the
  clear+repopulate routine logged in `RefreshLog`.
- `app/routes/views.py` — HTML routes: `/`, `/patient/<guid>`, POST `/refresh`.
- `app/routes/api.py` — JSON API: `/api/v1/series`, plus `/metadata`
  CapabilityStatement (Rule 15, FHIR R5).
- `app/templates/` — `base.html` (PDHC styling, 12px), `landing.html`,
  `patient.html` (Chart.js time scatter).
- `app/migrations/` — Alembic migrations (`flask db upgrade`).

## Data flow
1. User clicks "Refresh from gateway" → POST `/refresh`.
2. Server iterates `OrgMembership` rows for current user, calls
   `refresh_org(user, org)` for each.
3. `refresh_org` fetches bundle → normalises → replaces `ObservationCache`
   rows for that org → writes `RefreshLog` with count + status.
4. Landing page reads cache, filtered by `scope_to_user_orgs`.

## Environment variables (.env)
- `DATABASE_URL` — postgresql connection string
- `APP_PORT` — Flask port (default 9027)
- `AUTH_MODE` — `off` (dev) or `sso` (prod)
- `GATEWAY_BASE_URL` — e.g. `https://gateway.pdhc.se`
- `GATEWAY_TOKEN` — bearer token (keep in `.env` only; see API keys)
- `SECRET_KEY` — Flask session secret
- `OBSERVATION_CACHE_TTL_HOURS` — retention TTL for cached observations
  (default 48; see "ObservationCache retention" below)

## ObservationCache retention (PDL Ch 4 §§ 3-4, ticket #213)

ObservationCache rows are a **derived, time-bounded copy** of patient
observations the dashboard pulled from gateway. They must not survive
indefinitely — the source of truth (gateway, CDRs) may block, scrub,
or update a row, and a stale dashboard copy would defeat both
right-to-block (PDL Ch 4 § 4) and need-to-know (PDL Ch 4 § 1).

The retention policy has two parts:

1. **Time-based sweep.** Rows whose `fetched_at` is older than
   `OBSERVATION_CACHE_TTL_HOURS` (default 48h) are removed by the
   `flask cache-sweep` CLI. Run hourly from cron on the macmini:
   ```
   0 * * * * cd /usr/local/www/dashboard.pdhc/current \
              && docker exec dashboard_pdhc_app flask cache-sweep \
              >> shared/logs/cache_sweep.log 2>&1
   ```
   `flask cache-sweep --dry-run` reports the count that would be
   removed without touching the table — useful when tuning TTL.

2. **Targeted admin scrub.** SU admins can immediately drop rows
   matching `patient_guid` / `org_guid` / both via
   `POST /admin/cache/scrub`:
   ```json
   {
     "patient_guid": "...",     // optional
     "org_guid":     "...",     // optional; at least one required
     "reason":       "patient deletion request"
   }
   ```
   The endpoint writes a `dashboard_audit` row with
   `event_type='cache_scrub'`, `admin_justification=<reason>`,
   `n_rows_returned=<deleted_count>`, and a `payload_snapshot` JSONB
   carrying the verbatim filter + count. Non-SU callers get 403; an
   empty filter returns 400 (a no-filter scrub would wipe everything).

   Audit consumers (`/admin/audit`, #215) can join `cache_scrub`
   rows with the same patient's `read` / `admin_override` rows to
   reconstruct who saw what before it was scrubbed.

## API keys (Rule 8)
- **Storage**: `.env` only, never committed. `.gitignore` excludes `.env`.
- **Rotation**: generate a new token via the gateway admin UI, update
  `GATEWAY_TOKEN` in `.env`, restart with `./start.sh`.
- **Expiry**: tokens expire at 90 days; set a calendar reminder at 75 days.
- **Revocation**: revoke in the gateway admin UI immediately on compromise;
  rotate per above.

## Endpoints
| Path | Method | Purpose |
|------|--------|---------|
| `/healthz` | GET | liveness + current AUTH_MODE |
| `/metadata` | GET | FHIR R5 CapabilityStatement |
| `/` | GET | landing page (eligible patients + optional cohort curves) |
| `/patient/<guid>` | GET | patient dashboard |
| `/refresh` | POST | pull observations from gateway for user's orgs |
| `/api/v1/series?patient&concept` | GET | FHIR Bundle of Observations |
| `/admin/cache/scrub` | POST | SU-only: drop ObservationCache rows by patient/org (#213) |
| `/admin/audit` | GET | SU-only: browse `dashboard_audit` rows with filters + pagination (#215) |
| `/admin/audit/export.csv` | GET | SU-only: CSV export of the filtered set (cap 50000 rows) (#215) |

## Running locally
```
./start.sh
```
- Kills anything on 9026–9029
- Ensures Docker Desktop is up
- Starts Postgres via docker-compose
- Runs Alembic migrations
- Starts Flask on 9027
- Ctrl+C → `docker compose down` + venv deactivate

## Tests
```
app/.venv/bin/python -m pytest app/tests
./scripts/test_api.sh   # exercises live endpoints against a running instance
```