appointment-manager

# appointment-manager

Local-first healthcare appointment tracker with checklist and document support.

## When to use

- User wants to schedule a new appointment
- User needs to view upcoming appointments
- User wants to manage a pre-appointment checklist
- User needs to attach a document (referral, test results) to an appointment
- User wants to export appointment history for their healthcare provider
- User wants to manage their list of healthcare providers

## Privacy model

All data stored locally: SQLite at `./data/appointments.db`, attachments in `./attachments/`. No external transmission. Appointment notes never appear in log output.

## Prerequisites

- appointment-manager running: `pnpm dev` or `docker compose up -d`
- Server at `http://localhost:3850`

## Key API operations

### Get upcoming appointments

```bash
curl http://localhost:3850/api/appointments/upcoming
```

### Create an appointment

```bash
curl -X POST http://localhost:3850/api/appointments \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Annual Check-up",
    "appointment_type": "general",
    "provider_id": 1,
    "scheduled_at": "2026-03-24T10:00:00",
    "duration_mins": 60,
    "location": "Sample Medical Centre"
  }'
```

### Update appointment status

```bash
curl -X PATCH http://localhost:3850/api/appointments/1/status \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'
```

### Add a checklist item

```bash
curl -X POST http://localhost:3850/api/appointments/1/checklist \
  -H "Content-Type: application/json" \
  -d '{"text": "Bring insurance card", "sort_order": 1}'
```

### Toggle checklist item

```bash
curl -X PATCH http://localhost:3850/api/checklist/3 \
  -H "Content-Type: application/json" \
  -d '{"completed": 1}'
```

### Upload attachment

```bash
curl -X POST http://localhost:3850/api/appointments/1/attachments \
  -F "file=@/path/to/referral.pdf"
```

### Download CSV

```bash
curl -o appointments.csv http://localhost:3850/api/export/csv
```

## API Reference

| Endpoint | Method | Description |
|---|---|---|
| `/api/appointments` | GET | List appointments (status, from, to) |
| `/api/appointments` | POST | Create appointment |
| `/api/appointments/upcoming` | GET | Next 30 days |
| `/api/appointments/:id` | GET | Detail with checklist and attachments |
| `/api/appointments/:id` | PUT | Update appointment |
| `/api/appointments/:id/status` | PATCH | Update status |
| `/api/appointments/:id` | DELETE | Delete with cascade |
| `/api/providers` | GET | List providers |
| `/api/providers` | POST | Add provider |
| `/api/providers/:id` | PUT | Update provider |
| `/api/providers/:id` | DELETE | Delete provider |
| `/api/appointments/:id/checklist` | GET | Checklist items |
| `/api/appointments/:id/checklist` | POST | Add item |
| `/api/checklist/:itemId` | PATCH | Toggle / update item |
| `/api/checklist/:itemId` | DELETE | Remove item |
| `/api/appointments/:id/attachments` | POST | Upload file |
| `/api/attachments/:id` | GET | Download file |
| `/api/attachments/:id` | DELETE | Delete file |
| `/api/export/csv` | GET | CSV export |
| `/api/export/pdf` | GET | PDF export |
| `/api/settings` | GET | Settings |
| `/api/settings` | PATCH | Update settings |

## Appointment status values

| Status | Description |
|---|---|
| `upcoming` | Scheduled, not yet occurred |
| `completed` | Appointment attended |
| `cancelled` | Appointment cancelled |
| `rescheduled` | Moved to a new time |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3850` | Server port |
| `DATA_DIR` | `./data` | SQLite location |
| `ATTACHMENTS_DIR` | `./attachments` | File storage |
| `EXPORT_DIR` | `./exports` | CSV/PDF output |
| `LOG_LEVEL` | `info` | debug / info / warn / error |
| `PIN_LOCK` | `0` | 1 to require PIN |
| `MAX_ATTACHMENT_MB` | `10` | Upload size limit |
| `NODE_ENV` | `development` | development / production |

## Troubleshooting

### Reminder notifications not appearing

1. Check `Notification.permission` in the browser console - must be `'granted'`
2. Ensure WebSocket connection is open: check network tab for /ws
3. On macOS, check System Settings - Notifications for the browser

### File upload rejected

1. Check file size: max is `MAX_ATTACHMENT_MB` (default 10 MB)
2. Check MIME type: allowed are `application/pdf`, `image/jpeg`, `image/png`, `image/webp`
3. Verify `ATTACHMENTS_DIR` exists and is writable