medication-tracker

# medication-tracker

Local medication schedule tracker with dose logging and adherence monitoring.

## When to use

- User wants to add a medication to their schedule
- User needs to log a taken or skipped dose
- User wants to review adherence statistics
- User needs to check upcoming refill dates
- User is preparing a medication summary for a healthcare provider

## Privacy model

All medication data stored locally in SQLite at `./data/medications.db`. No external transmission. Interaction data uses a built-in reference table only.

## Prerequisites

- medication-tracker running: `pnpm dev` or `docker compose up -d`
- Server at `http://localhost:3848`

## Key API operations

### Log a taken dose

```bash
curl -X POST http://localhost:3848/api/doses/taken \
  -H "Content-Type: application/json" \
  -d '{"medication_id": 1, "scheduled_time": "2026-03-20T08:00:00"}'
```

### Get today's schedule

```bash
curl http://localhost:3848/api/schedule/today
```

### Get adherence summary

```bash
curl "http://localhost:3848/api/adherence/summary?days=30"
```

### Check interactions

```bash
curl http://localhost:3848/api/interactions
```

Response includes `disclaimer` field - always display to user.

## API Reference

| Endpoint | Method | Description |
|---|---|---|
| `/api/medications` | GET | List medications |
| `/api/medications` | POST | Add medication |
| `/api/medications/:id` | PUT | Update |
| `/api/schedule/today` | GET | Today's dose schedule |
| `/api/schedule/:date` | GET | Schedule for date (YYYY-MM-DD) |
| `/api/doses/taken` | POST | Log dose taken |
| `/api/doses/skipped` | POST | Log dose skipped |
| `/api/doses/today` | GET | Today's dose status |
| `/api/adherence/summary` | GET | Overall adherence % |
| `/api/adherence/:id` | GET | Per-medication adherence |
| `/api/refills` | GET | All medications with refill info |
| `/api/refills/upcoming` | GET | Refills due soon |
| `/api/interactions` | GET | Check current medications |
| `/api/settings` | GET | Settings |
| `/api/settings` | PATCH | Update settings |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3848` | Server port |
| `DATA_DIR` | `./data` | SQLite location |
| `LOG_LEVEL` | `info` | debug / info / warn / error |
| `NODE_ENV` | `development` | development / production |
| `REMINDER_LEAD_MINS` | `15` | Minutes before dose for reminder |

## Interaction warnings

The interaction check endpoint always returns a `disclaimer` field. Display this to users before showing any interaction data. The database is limited and informational only - not a clinical decision support tool.

## Adherence thresholds

| Rate | Status |
|---|---|
| 90-100% | Excellent (green) |
| 80-89% | Good (blue) |
| 60-79% | Needs attention (amber) |
| below 60% | Low (red) |