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.
| 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.
625275e55b