Provider Directory Service — Service Overview
Status: populated
Owner: TBD
Last updated: 2026-04-17
Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
The provider-directory-service is the authoritative registry of clinicians and care-delivery service endpoints within the Ghasi-eHealth platform. It owns Practitioner identities, their roles and privileges, licenses-to-practice, credential lifecycle, specialties, and service/endpoint discovery. It exposes this data to scheduling, orders, clinical notes, billing, and interoperability partners.
2. Bounded Context
Provider Directory — classified as Supporting. It sits between Identity (who is the user) and clinical services (what can they do). It complements facility-service by linking providers to nodes, but it owns the clinical-professional view (license, specialty, credentials) that facility-service does not.
3. Responsibilities
| Area | What provider-directory Owns |
|---|
| Practitioner identity | Practitioner aggregate: name variants, telecoms, specialties, employment status |
| Practitioner roles | PractitionerRole with scope (department/location) + privileges |
| Credentials / licenses | Credential entity — issuing authority, expiry, status; notification on expiry |
| Service endpoints | ServiceEndpoint — FHIR / HL7 URLs per organisation/location |
| Healthcare services | HealthcareService — service offerings bound to location + specialty |
| Specialty taxonomy | Deployment-configurable taxonomy references (SNOMED, local) |
| National IDs | Medical-council registration numbers, tazkira-linked identifiers (AFG), DHA/DoH numbers (UAE) |
| Multi-script names | Local script + Latin transliteration; display-order rules |
| Search & listings | Full-text + filter search; deterministic ordering |
| FHIR projection | Practitioner, PractitionerRole, HealthcareService, Endpoint |
| Credential expiry events | Lifecycle events for privilege gating upstream |
4. Non-Responsibilities
| Area | Owner | Why Not provider-directory |
|---|
| Login / credentials / MFA | identity-service | Identity authenticates users; provider-directory describes their clinical profile |
| Node assignments (provider ↔ location) | facility-service (ProviderNodeMembership) | Facility owns the graph membership edge; provider-directory stores primary profile and reacts to membership events |
| Scheduling availability | scheduling-service | Scheduling consumes provider + working hours from facility |
| Privilege evaluation at runtime | access-policy | Provider-directory publishes privileges; access-policy decides |
| Billing NPI equivalents | billing-service | Billing consumes; does not own |
5. Dependencies
5.1 Upstream
| Dependency | Pattern | Purpose |
|---|
| identity-service | CF | JWT validation; sub claim links to Practitioner.userId |
| tenant-service | Shared kernel | Tenant isolation |
| facility-service | Event + RPC | Node memberships, locations |
| terminology-service | RPC | Specialty taxonomy lookup |
| access-policy | RPC | Write authorization |
| Licensing (platform-admin) | RPC | Module entitlement ehr.provider-directory |
5.2 Downstream Consumers
| Consumer | Pattern | What they consume |
|---|
| scheduling-service | Event + RPC | Practitioner profile, role, working hours |
| orders/medication/laboratory/radiology | Event + RPC | Privilege gating (can-order, can-prescribe) |
| patient-chart-service | RPC | Attribution on clinical notes |
| billing-service | Event | Provider identifiers for claims |
| interop-service | Event | FHIR Practitioner / Endpoint |
| facility-service | Event | Creates ProviderNodeMembership when practitioner.created arrives |
| population-health-service | Event | Workforce analytics |
5.3 Events Consumed
| Event | Producer | Purpose |
|---|
identity.user.registered.v1 | identity-service | Optional JIT shadow Practitioner for clinician users |
tenant.tenant.created.v1 | tenant-service | Initialize specialty taxonomy defaults |
facility.provider_membership.assigned.v1 | facility-service | Update cached node context for provider |
gdpr.subject_request.received.v1 | platform | Participate in erasure flow |
6. Slice Involvement
| Slice | Scope | Milestone |
|---|
| S0 — Foundation | Practitioner CRUD, role assignment, specialty catalog, search, FHIR Practitioner | M0 |
| S1 — Credentials | License + credential lifecycle, expiry notifications, privilege gating, endpoint registry | M1 |
| S2 — Interop | Full FHIR R4 (PractitionerRole, HealthcareService, Endpoint), HL7 v2 PV1/ORC alignment | M2 |
| S4 — Enterprise | National registry bridges (AFG medical council, UAE DHA), multi-script UX polish | M3 |
7. Architectural Freeze Points
| Freeze | What | By |
|---|
| F03 | PractitionerId, PractitionerRoleId, CredentialId, EndpointId, HealthcareServiceId branded types | End of M0 |
| F01 | EventEnvelope on provider_directory.* events | End of M0 |
8. Readiness Levels
| Level | Target | Capabilities |
|---|
| L2 | M0 | CRUD + search operational; manual monitoring |
| L3 | M1 | Credential lifecycle, privilege gating, contract tests, SLOs |
| L4 | M3 | National registry integration, chaos-tested, multi-region |
9. Architecture Diagram
10. Key Design Decisions
- Practitioner is separate from User. Identity owns login; provider-directory owns the clinical-professional view. Link via
userId (optional — not every practitioner has a system login).
- Credentials gate privileges. A provider without an active license cannot be granted ordering/prescribing privileges (BR-PROV-001).
- Specialty taxonomy is configurable. Deployments may use SNOMED CT, local codes, or both; provider-directory stores the code + system; terminology-service resolves.
- Search is ElasticSearch / OpenSearch-backed for fuzzy name matches across scripts.
- Node membership lives in facility-service. provider-directory emits
practitioner.created and consumes facility.provider_membership.* for cache.
- FHIR is a projection.
Practitioner, PractitionerRole, HealthcareService, Endpoint are generated from internal domain.