Patient cross-tenant appointments

Reference for the three workstreams that turn Kulcare from a fragmented per-clinic experience into a unified patient surface, while keeping clinic-side data tenant-isolated under RLS.

Status: Backend complete. Frontend wiring (clinic-app PatientPicker + patient-side booking switch in patient/) deferred to follow-ups.

Patient-side codebase: this doc refers to the in-monorepo patient/ Vite app. The legacy patient-app (React 17, decommissioned) is no longer relevant.

Brainstorm: docs/brainstorms/2026-05-06-patient-cross-tenant-appointments-brainstorm.md

Plans: Workstream B · Workstream C

What this enablesCopy Anchor Link

Three coupled capabilities:

1. Patient sees all appointments across all facilities — GET /patient/appointments aggregates practitioner appointments (per-tenant via RLS) with vendor appointments (no tenant) into one chronological list with enriched payload.

2. Clinic finds any patient at booking time — GET /clinical/patients/federated_search returns three buckets (in_clinic, in_kulcare, no_match) so a clinic can pick up a patient who's already in the Kulcare network without a manual intake step. Privacy-guarded — never leaks which other clinics a patient has visited.

3. Patient books at any clinic from the patient app — POST /patient/appointment_orders carries the Identity::User JWT, sets RLS to the target tenant, auto-provisions a Clinical::Patient if needed, and creates the appointment. First-time-at-tenant requires explicit consent.

ArchitectureCopy Anchor Link

The three patient identity layersCopy Anchor Link

Already in the schema, exposed as APIs by this work:

Same human at three facilities = three Clinical::Patient rows, all linked to one Identity::Patient, all linked to one Identity::User (when signed up).

Cross-tenant fan-out patternCopy Anchor Link

Implemented in Patient::Appointments::ListService and Clinical::Patients::LongitudinalRecordService. Sets app.current_tenant_id per-tenant, queries within RLS, restores in ensure:

def with_rls_context(tenant_id)
  conn = ActiveRecord::Base.connection
  previous_tenant = Shared::Current.tenant

  conn.execute(
    ActiveRecord::Base.sanitize_sql(
      ["SELECT set_config('app.current_tenant_id', ?, true)", tenant_id.to_s]
    )
  )
  Shared::Current.tenant = Identity::Tenant.find(tenant_id)

  yield
ensure
  Shared::Current.tenant = previous_tenant
  conn.execute("SELECT set_config('app.current_tenant_id', '', true)")
end

Vendor appointments use a single global query (no RLS context needed) and union with the practitioner results. Both are sorted by start_time DESC and paginated.

Pending refactor: this pattern is duplicated across three call sites. Tracked for extraction into Shared::Tenancy::RlsContext in #1344 item 12.

Workstream A — GET /patient/appointmentsCopy Anchor Link

Backed by: Patient::Appointments::ListService Blueprint: Patient::AppointmentBlueprint :patient_card Auth: Identity::User JWT (skips tenant context)

Response shapeCopy Anchor Link

{
  "data": [{
    "id": "...",
    "appointment_time": "2026-05-08T10:00:00Z",
    "appointment_status": "booked",
    "booked_at": "2026-05-06T07:00:00Z",
    "appointment_type": "fixed",
    "couple_session": false,
    "doctor_details": {
      "id": "...",
      "kind": "practitioner",
      "name": "Dr. Asha Sharma",
      "photo": "https://cdn.kulcare/avatars/asha.png"
    },
    "clinic_details": {
      "id": "...",
      "name": "Mumbai Heart Clinic",
      "location": {
        "address_line_1": "12 Marine Dr",
        "city": "Mumbai",
        "state": "MH",
        "postal_code": "400001"
      }
    },
    "chief_complaint": "fever, 3 days",
    "reason_codes": ["fever, 3 days"],
    "tenant_id": "..."
  }],
  "meta": { "total": 5, "page": 1, "limit": 20, "fan_out": 3 }
}

fan_out is the number of tenants iterated (capped at 10 per request via MAX_TENANTS_PER_REQUEST).

Vendor vs practitioner appointmentsCopy Anchor Link

Both surface here — doctor_details.kind distinguishes:

• Practitioner — tenant-scoped, appointable_type = 'Identity::Practitioner', anchored on patient_id. Has clinic_details.
• Vendor — no tenant (tenant_id IS NULL), appointable_type = 'Identity::Vendor', anchored on attendee_user_id. clinic_details is null; vendor's service_category exposed instead of photo.

What this is NOTCopy Anchor Link

• Not the LHR. Appointments are forward-looking scheduling. LHR (Clinical::Patients::LongitudinalRecordService) is for retrospective clinical history (encounters, conditions, observations, prescriptions, allergies, documents).
• Not authoritative for editing. POST /patient/appointment_orders creates; PUT /patient/appointments/:id/cancel and /confirm mutate state. This endpoint is read-only.

Workstream B — GET /clinical/patients/federated_searchCopy Anchor Link

Backed by: Clinical::Patients::FederatedSearchService Auth: Tenant-scoped clinic JWT, Pundit :search? policy

RequestCopy Anchor Link

GET /clinical/patients/federated_search?phone=9876543210&country_code=91&name=Asha

Required: at least one of phone, email, name. When phone is given, country_code is required — phone alone could match the same national number across countries.

ResponseCopy Anchor Link

{
  "data": {
    "in_clinic": [
      {
        "id": "...",
        "name": "Asha Sharma",
        "phone": "9876543210",
        "mrn": "MRN-0042",
        "email": "...",
        "age": 34,
        "gender": "female"
      }
    ],
    "in_kulcare": [
      {
        "identity_patient_id": "...",
        "identity_user_id": "...",
        "name": "Asha Sharma",
        "phone": "9876543210",
        "phone_country_code": "91",
        "age": 34,
        "gender": "female",
        "registered_via": "patient_app"
      }
    ],
    "no_match": []
  }
}

Privacy guaranteesCopy Anchor Link

• in_kulcare results never leak which other clinics a patient has visited. Only global Identity::Patient / Identity::User fields are exposed.
• registered_via exposes only the kind of registration source (patient_app if Identity::User exists, another_clinic otherwise). No clinic names, no clinic count.
• name search uses ActiveRecord::Base.sanitize_sql_like on the input plus a 3-character minimum so % / _ cannot enumerate the global identity table.

Auto-provision at bookingCopy Anchor Link

When the clinic picks an in_kulcare patient and confirms the booking, Orders::CreateAppointmentOrderService accepts these alternatives to patient_id:

# Existing path (unchanged):
Orders::CreateAppointmentOrderService.call(patient_id: '...', ...)

# New paths (Workstream B):
Orders::CreateAppointmentOrderService.call(identity_patient_id: '...', ...)
Orders::CreateAppointmentOrderService.call(identity_user_id: '...', ...)

The service:

1. Looks for an existing Clinical::Patient in the current tenant linked to the given Identity::Patient / Identity::User. If found, uses it.
2. If absent, calls Clinical::Patients::FindOrCreateService to provision a new Clinical::Patient linked to the existing identity layer.
3. Race-safe: rescues ActiveRecord::RecordNotUnique and re-reads. Backed by partial unique indexes on both (tenant_id, user_id) and (tenant_id, identity_patient_id).

Audit logging — events B1 and B2Copy Anchor Link

All emissions route through Audit::Dispatch (contract). Don't write Audit::PhiAccessLog.create! directly.

reason_detail stores structured metadata as JSON (no metadata jsonb column on PhiAccessLog yet — see #1344 item 8).

Workstream C — POST /patient/appointment_ordersCopy Anchor Link

Backed by: Patient::AppointmentOrders::CreateService Auth: Identity::User JWT Returns: Same shape as Workstream A's :patient_card view

RequestCopy Anchor Link

{
  "tenant_id": "...",
  "facility_id": "...",
  "practitioner_id": "...",
  "appointment_type": "fixed",
  "start_time": "2026-06-01T10:00:00Z",
  "end_time": "2026-06-01T10:30:00Z",
  "reason_codes": ["fever, 3 days"],
  "patient_instruction": "Bring previous reports",
  "consent_acknowledged": true
}

status is not accepted — patient cannot pre-set the appointment status. Service hard-defaults to booked for non-walk-in.

Service flowCopy Anchor Link

1. Validate tenant + facility (must exist, tenant must be active, facility must be operational? and belong to tenant).
2. Open ActiveRecord::Base.transaction.
3. Inside the transaction, set RLS context to the target tenant via with_rls_context.
4. Look for existing Clinical::Patient for current_user in target tenant. If none:
   • Validate consent_acknowledged: true (else fail with :consent_required).
   • Auto-provision via Clinical::Patients::FindOrCreateService wrapped in a savepoint (requires_new: true) so a RecordNotUnique on concurrent insert doesn't poison the outer transaction.
   • Fire C1 (Audit::ConsentAuditLog) and C2 (Audit::PhiAccessLog).
5. Delegate to Clinical::Appointments::CreateService (existing) for the actual appointment creation. Reuses validation, slot lookup, SMS notifications, reminder scheduling.
6. Return enriched payload via Patient::AppointmentBlueprint :patient_card.

ConsentCopy Anchor Link

Server-enforced: consent_acknowledged: true is required only on first-time bookings at this tenant. Returning patients (already have a Clinical::Patient) need no consent — consent was given the first time.

Frontend should detect is_first_time_at_this_facility: true from the practitioner search and render the consent prompt ("Your name and phone will be shared with [Facility Name]. Continue?") before Confirm.

subject_user vs acting_userCopy Anchor Link

Both are passed through:

• subject_user — the user whose Clinical::Patient is created (the dependent in a guardian-on-behalf-of flow).
• acting_user — the human who clicked Confirm (the guardian in a guardian-on-behalf-of flow).

Audit logs record both for HIPAA forensics. ConsentAuditLog.scope and PhiAccessLog.reason_detail include acting_user_id. Defaults to subject_user when no X-On-Behalf-Of header.

Audit logging — events C1, C2Copy Anchor Link

IP address is captured natively in Audit::ConsentAuditLog#ip_address. User-agent goes in scope.user_agent.

Error contractCopy Anchor Link

What's deferredCopy Anchor Link

File mapCopy Anchor Link

ReferencesCopy Anchor Link

• Brainstorm: docs/brainstorms/2026-05-06-patient-cross-tenant-appointments-brainstorm.md
• Plans: docs/plans/2026-05-06-feat-clinic-federated-patient-search-plan.md, docs/plans/2026-05-06-feat-patient-app-authenticated-booking-plan.md
• Polymorphic Appointment doc: docs/guides/developer/clinical/appointments/polymorphic-appointable.md
• Patient domain README: docs/guides/developer/patient-domain/README.md
• PRs: #1335 (A), #1342 (A follow-up), #1341 (B), #1343 (B follow-up), #1345 (C), #1348 (C follow-up)