# Healthcare API Connection Report

**Service:** `healthcare-service` v0.13.7.0  
**BFF:** `/api/healthcare/*` → port 8010  
**Client:** `frontend/src/modules/healthcare/services/healthcare-api.ts`

---

## Connection Architecture

```
Browser (portal page)
  → healthcareApi.* (tenant + JWT headers)
  → /api/healthcare/* (Next.js route handler)
  → healthcare-service:8010/api/v1/*
```

All mutations use optimistic invalidation of TanStack Query keys scoped by tenant.

---

## API Surface Used by UI

### Foundation (Phase 13.0)

| Resource | List | Get | Create | Update | Delete | UI Screen |
|----------|------|-----|--------|--------|--------|-----------|
| clinics | ✅ | ✅ | ✅ | ✅ | ✅ | `ClinicsResourcePage` |
| branches | ✅ | ✅ | ✅ | ✅ | ✅ | `BranchesResourcePage` |
| departments | ✅ | ✅ | ✅ | ✅ | ✅ | `DepartmentsResourcePage` |
| doctors | ✅ | ✅ | ✅ | ✅ | ✅ | `DoctorsResourcePage` |
| patients | ✅ | ✅ | ✅ | ✅ | ✅ | `PatientsResourcePage` |
| external_providers | ✅ | ✅ | ✅ | ✅ | ✅ | `ExternalProvidersResourcePage` |
| settings | ✅ | — | upsert | upsert | — | `SettingsResourcePage` |
| audit | ✅ | — | — | — | — | `AuditExplorerPage` |
| permissions/catalog | ✅ | — | — | — | — | `PermissionsCatalogPage` |

### Appointments & Visits (13.1–13.2)

| Resource | Operations wired in UI |
|----------|------------------------|
| appointments | list, book, **confirm**, **cancel**, **no-show** |
| waiting_list | list, create |
| visit_sessions | list, create, **start**, **finish**, **defer**, **callNext** |
| schedules | list, create |
| availability_windows | list, create |
| doctor_panel/dashboard | doctor dashboard stats |
| visit_notes | via doctor encounters (create in records flow) |

### Clinic Admin (13.3)

| Resource | UI |
|----------|-----|
| clinic_services | CRUD create + list |
| staff_assignments | CRUD create + list |
| clinic_policies | CRUD create + list |
| operating_hours_policies | list (via resources) |

### Patient Portal (13.4)

| Endpoint | UI Page |
|----------|---------|
| patient-portal/me | Patient profile |
| patient-portal/appointments | upcoming / past / cancel |
| POST patient-portal/appointments | book wizard |
| patient-portal/documents | lab results, reviews, attachments |
| patient-portal/notification-preferences | notifications toggle |

### Medical Records (13.5–13.6)

| Endpoint | UI |
|----------|-----|
| medical-records POST/GET | lookup panel + create |
| clinical-lists + conditions/allergies/medications/immunizations | tabs + add |
| encounters create/update/finalize | encounters panel |
| prescription-orders full pipeline | doctor + pharmacy portals |
| pharmacies | admin + pharmacy dashboard |

### Delivery (13.7)

| Endpoint | UI |
|----------|-----|
| delivery-integrations | pharmacy delivery page |
| delivery-job-intents | pharmacy delivery page |

### Integrations (accounting / CRM / communication)

Mapped via `external_providers` filtered by `provider_kind` on payments, messages, income pages.

---

## Headers & Auth

| Header | Source |
|--------|--------|
| `Authorization` | Keycloak JWT via `getValidAccessToken()` |
| `X-Tenant-ID` | `useTenantId()` |
| `X-Patient-ID` | patient portal routes only |

401 triggers silent refresh via `refreshSession()`.

---

## Validation

| Check | Result |
|-------|--------|
| All entity screens call `healthcareApi` | ✅ |
| No hardcoded mock arrays in module pages | ✅ |
| BFF route exists | `app/api/healthcare/[...path]/route.ts` |
| Error mapping | `HealthcareApiError` with code + message |

---

## Gaps (backend)

- Collection list for `medical-records` and `encounters` not in client API — UI uses ID lookup / create flows.
- Dedicated insurance, laboratory, imaging request resources not in v0.13.7 OpenAPI — documented as future endpoints.