vitals-dashboard

# vitals-dashboard

Local-first vital signs tracker with trend analysis and export.

## When to use

- User wants to log a vital sign reading (blood pressure, heart rate, weight, blood glucose, temperature)
- User needs to review trends or rolling averages for a vital type
- User wants to check or acknowledge alerts for out-of-range readings
- User is preparing a vital signs summary for a healthcare provider
- User wants to explore correlations between vital sign pairs

## Privacy model

All data stored locally in SQLite at `./data/vitals.db`. No external transmission. Vital values never appear in log output.

## Prerequisites

- vitals-dashboard running: `pnpm dev` or `docker compose up -d`
- Server at `http://localhost:3849`

## Key API operations

### Log a reading

```bash
curl -X POST http://localhost:3849/api/vitals \
  -H "Content-Type: application/json" \
  -d '{"vital_type": "heart_rate", "value1": 72, "recorded_at": "2026-03-20T08:14:00"}'
```

### Log blood pressure (two values)

```bash
curl -X POST http://localhost:3849/api/vitals \
  -H "Content-Type: application/json" \
  -d '{"vital_type": "blood_pressure", "value1": 118, "value2": 76, "recorded_at": "2026-03-20T08:00:00"}'
```

### Get latest reading per vital type

```bash
curl http://localhost:3849/api/vitals/latest
```

### Get readings for a type with date range

```bash
curl "http://localhost:3849/api/vitals?type=blood_pressure&from=2026-03-01&to=2026-03-20"
```

### Get active alerts

```bash
curl http://localhost:3849/api/alerts
```

### Acknowledge an alert

```bash
curl -X PATCH http://localhost:3849/api/alerts/3/acknowledge
```

### Get correlations

```bash
curl "http://localhost:3849/api/correlations?days=90"
```

### Download CSV

```bash
curl -o vitals.csv http://localhost:3849/api/export/csv
```

### Download PDF report

```bash
curl -o report.pdf http://localhost:3849/api/export/pdf
```

## API Reference

| Endpoint | Method | Description |
|---|---|---|
| `/api/vital-types` | GET | List all vital types with thresholds |
| `/api/vitals` | POST | Log a reading |
| `/api/vitals` | GET | List readings (type, from, to, limit) |
| `/api/vitals/:id` | GET | Single reading |
| `/api/vitals/:id` | DELETE | Delete reading |
| `/api/vitals/latest` | GET | Latest per vital type |
| `/api/alerts` | GET | Unacknowledged alerts |
| `/api/alerts/:id/acknowledge` | PATCH | Mark acknowledged |
| `/api/correlations` | GET | Pearson r between vital pairs |
| `/api/export/csv` | GET | CSV download |
| `/api/export/pdf` | GET | PDF report download |
| `/api/settings` | GET | Settings |
| `/api/settings` | PATCH | Update settings |

## Vital Types

| key | label | unit | alert_high |
|---|---|---|---|
| `blood_pressure` | Blood Pressure | mmHg | 140 (systolic) |
| `heart_rate` | Heart Rate | bpm | 120 |
| `weight` | Weight | kg | none |
| `blood_glucose` | Blood Glucose | mmol/L | 11.0 |
| `temperature` | Temperature | degC | 38.5 |

## Alert thresholds

Alerts are generated automatically when a reading exceeds `alert_low` or `alert_high` for the vital type. The disclaimer "This tool does not provide medical advice. Consult your healthcare provider." must be shown wherever alerts are displayed.

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3849` | Server port |
| `DATA_DIR` | `./data` | SQLite location |
| `EXPORT_DIR` | `./exports` | Output for CSV/PDF |
| `LOG_LEVEL` | `info` | debug / info / warn / error |
| `PIN_LOCK` | `0` | 1 to require PIN |
| `NODE_ENV` | `development` | development / production |

## Troubleshooting

### Alert not generated

1. Check that the vital type has `alert_high` or `alert_low` set: `GET /api/vital-types`
2. Verify the submitted value actually exceeds the threshold
3. Blood pressure: both value1 (systolic) and value2 (diastolic) are checked independently

### Correlation endpoint returns empty array

1. Ensure at least two vital types have 10+ readings on shared calendar dates
2. Increase the `days` query parameter to include more history

### PDF export hangs

1. Check that `EXPORT_DIR` exists and is writable
2. Verify pdfkit is installed: `pnpm list pdfkit`