Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Version: 1.0
Last Updated: 2026-03-27
Spec: specs/pm/specs/PM-38-intake-appointment-automation-provider-matching.md
Status: ✅ Complete

​
Overview

PM-38 auto-schedules intake appointments after CE-28 screening approval. This document maps cross-core integration points, event contracts, API contracts, and platform layer usage.

​
Integration Matrix

FromToPatternEvent/APIStatus
CE-28PM-38Event (FW-16)ce_screening_completed (disposition=proceed)📝 Planned
CE-29PM-38Data (prerequisite)pm_patients record exists before scheduling📝 Planned
PM-38PM-05/PM-03API (internal)PM-05: query available slots; PM-03: create appointment✅ Complete
PM-38PM-39Event (FW-16)pm_no_suitable_provider → waitlist entry📝 Planned
PM-38PM-40Event (FW-16)pm_appointment_created → pre-admission packet📝 Planned
PM-38PM-41DataMatch log analytics consumed by PM-41 dashboards📝 Planned
PM-38PM-42DataCoordinator task queue pulls appointment status📝 Planned
PM-38PM-02Data (optional)Insurance acceptance data for matching📝 Planned
PM-38RH-01Data (optional)Multi-pathway bed/program check📝 Planned

​
Event Contracts

​
Consumed Events

​
ce_screening_completed (from CE-28 via FW-16)

Canonical schema: See CE-28 Integration and EVENT_CONTRACTS.md for the authoritative payload definition. 
{
  event_id: uuid;
  source: 'ce-28';
  timestamp: string; // ISO 8601
  correlation_id: uuid;
  organization_id: uuid;
  data: {
    screening_id: uuid;
    lead_id: uuid;
    disposition: 'proceed' | 'waitlist' | 'refer_out' | 'decline';
    clinical_flags: string[];
    asam_score: number | null;
    recommended_level_of_care: string | null;
    needs_clinical_escalation: boolean;
    screener_id: uuid;
    screening_date: string; // ISO 8601
    program_type: 'residential' | 'iop' | 'php' | 'outpatient';
    sla_status: 'on_time' | 'missed';
  };
}
Filter: PM-38 only acts when disposition = "proceed".

​
Published Events

​
pm_appointment_created

{
  "event_type": "pm_appointment_created",
  "payload": {
    "appointment_id": "uuid",
    "patient_id": "uuid",
    "provider_id": "uuid",
    "organization_id": "uuid",
    "appointment_time": "ISO8601",
    "appointment_type": "intake_assessment",
    "screening_id": "uuid",
    "match_log_id": "uuid"
  }
}
Consumers: PM-40 (pre-admission packet), PM-41 (analytics), CL-40 (clinical intake trigger).

​
pm_no_suitable_provider

{
  "event_type": "pm_no_suitable_provider",
  "payload": {
    "screening_id": "uuid",
    "patient_id": "uuid",
    "organization_id": "uuid",
    "program_type": "string",
    "reason": "no_available_provider",
    "match_log_id": "uuid"
  }
}
Consumer: PM-39 (waitlist management).

​
API Contracts

​
PM-05 Availability Query (consumed by PM-38)

PM-05 provides provider schedule and availability data. PM-38 queries available slots filtered by specialty, site, insurance, and configurable availability window (intake_match_availability_days).
  • Returns: array of { provider_id, slot_time, slot_duration, location }

​
PM-03 Appointment Creation (consumed by PM-38)

PM-03 provides appointment CRUD. PM-38 creates intake appointments after matching.
  • POST /api/scheduling/appointments with { patient_id, provider_id, slot_time, type: 'intake', modality, site_id }
  • Returns: { appointment_id, status, appointment_time }

​
Coordinator Override

  • PATCH /api/appointments/{id}/override — See spec API Design section.

​
Platform Layer Usage

LayerUsage
FW-16 (Event)Subscribe to ce_screening_completed; publish pm_appointment_created and pm_no_suitable_provider
PF-05 (Org Context)Organization ID for tenant scoping
PF-30 (Permissions)pm.intake_match.view, pm.intake_match.override, pm.intake_match.configure, pm.appointments.create, pm.appointments.confirm
PF-10 (Notifications)Coordinator notifications on appointment creation, no-match, and override alerts

​
Security

  • All data scoped by organization_id; RLS enforced on pm_appointment_match_log
  • Edge function uses service role for INSERT; SECURITY DEFINER helper for user-facing SELECT
  • No PHI in event payloads beyond patient_id (resolvable by consumer with RLS)
  • SMS content follows HIPAA minimum necessary standard

​
Dependencies

DependencyRequired ByStatusNotes
PM-05/PM-03 API (slot query + appointment create)Phase 1-2✅ CompletePM-05 for availability; PM-03 for appointment CRUD
CE-28 event contract (ce_screening_completed)Phase 2📝 PlannedPayload schema above
CE-29 patient creationPhase 2📝 PlannedPatient must exist in pm_patients
PM-39 waitlist subscriptionPhase 4📝 PlannedConsumes pm_no_suitable_provider
PM-02 insurance data (optional)Phase 1Degraded-okDefault to all-insurance if unavailable

​
Open Questions

  • PM-10 API contract finalization — Resolved: PM-05 for availability, PM-03 for appointment CRUD
  • CE-28 event payload finalization (confirm modality_preference field name) — Resolved: field removed from payload; scheduling uses program_type and site preferences
  • SMS consent: Confirm CE-28 captures TCPA consent for automated messaging