Appointment Scheduling – Integration

{
  "event_type": "appointment_scheduled",
  "organization_id": "org-uuid",
  "appointment_id": "appointment-uuid",
  "actor_id": "scheduler-user-uuid",
  "patient_id": "patient-uuid",
  "provider_id": "provider-uuid",
  "appointment_type": "individual",
  "start_datetime": "2026-03-01T09:00:00Z",
  "end_datetime": "2026-03-01T10:00:00Z",
  "is_telehealth": false,
  "status": "scheduled",
  "timestamp": "2026-02-19T12:00:00Z"
}

{
  "event_type": "encounter_completed",
  "organization_id": "org-uuid",
  "encounter_id": "encounter-uuid",
  "appointment_id": "appointment-uuid",
  "patient_id": "patient-uuid",
  "provider_id": "provider-uuid",
  "encounter_type": "outpatient",
  "place_of_service": "11",
  "timestamp": "2026-02-19T12:00:00Z"
}

// Check provider availability before scheduling
const { data: blocks } = await supabase
  .from('pm_provider_schedules')
  .select('start_datetime, end_datetime, schedule_type')
  .eq('organization_id', orgId)
  .eq('provider_id', providerId)
  .gte('start_datetime', windowStart)
  .lte('end_datetime', windowEnd);

import { sendNotification } from '@/platform/notifications';

// Schedule appointment reminder
await sendNotification({
  userId: patientPortalUserId,          // or provider userId
  type: 'info',
  title: 'Appointment Reminder',
  message: `Your appointment is on ${formatDate(startDatetime)}`,
  channels: ['sms', 'email'],           // per pm_module_settings config
  scheduledAt: reminderScheduledAt,
});

// Store confirmation in pm_appointment_reminders
await supabase.from('pm_appointment_reminders').insert({
  organization_id: appointment.organization_id,
  appointment_id: appointment.id,
  reminder_type: channel,
  scheduled_at: reminderScheduledAt,
  delivery_status: 'pending',
});

Is the organization behavioral health (standard service types)?
├── YES → Use PF-15 picklist 'pm_appointment_types' (org-customizable)
│         Seed defaults: individual, family, intake, medication_management,
│                        telehealth, walk_in
│         No CHECK constraint — picklist enforces at application layer
└── NO  → (Not applicable: all Encore OS orgs are behavioral health)

Is PM-13 available?
├── NO (Phase 1) →
│     telehealth_url is nullable TEXT
│     Allow manual entry only
│     COMMENT ON COLUMN documents lifecycle intent
│     Do NOT store long-lived production video links
│     Audit trail: is_telehealth flag + created_by + updated_at
└── YES (Phase 2) →
      On-demand URL generation at check-in
      URL expiry enforcement (max 2h)
      Access logging in pm_encounters
      Encryption at rest via Supabase Vault

Does the appointment have is_recurring = true?
├── YES → recurrence_rule JSONB MUST follow iCal RRULE RFC 5545
│         Example: { "FREQ": "WEEKLY", "BYDAY": "MO,WE,FR", "COUNT": 12 }
│         series_id MUST be set (UUID shared across all instances)
│         Use rrule npm library for client-side parsing/generation
└── NO  → recurrence_rule = NULL, series_id = NULL

User schedules appointment for provider at time T:
├── Query pm_appointments WHERE provider_id = X AND start_datetime <= T+duration AND end_datetime >= T AND deleted_at IS NULL
│   └── Query pm_provider_schedules (PM-05) for availability blocks
│
├── Conflict found?
│   ├── User has pm.scheduling.override_double_booking permission?
│   │   ├── YES → Show conflict warning; allow save with confirmation
│   │   └── NO  → Block save; show next available slots
│   └── NO conflict → Proceed normally
└── PM-05 tables missing? → Stub check; log TODO; allow save