appointment-manager

name	appointment-manager
description	Schedule and track healthcare appointments, manage provider contacts, build pre-appointment checklists, attach documents, receive reminders, and export appointment history. Use when a user needs to add, view, update, or export healthcare appointments.

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

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

Create an appointment

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

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

Add a checklist item

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

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

Upload attachment

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

Download CSV

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

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