Providers

The provider service manages healthcare providers (GPs, hospitals, specialists, pharmacies), their credentialing, and network participation. Bookable time and appointments hang off providers but are owned by the care service (see Care Pathways).

Field reference: full columns, types and nullability live in the catalog: glossary terms Provider, CredentialingRequest, ProviderSlot, Appointment. This page is the narrative.

Provider

A Provider is a credentialed healthcare organisation or individual. locator is the external reference; npi is the clinical identifier; both are unique. A provider may also be a Party of type PROVIDER via party_id (nullable; not every provider is also modelled as a party).

NPI is a US-style identifier

NPI (US National Provider Identifier) is used as the clinical key, but this is a UK platform; the equivalent registers are GMC (doctors), GPhC (pharmacists), ODS (organisations) and CQC (regulated activity). Treat npi as a stand-in until the UK identifier scheme is settled.

Credentialing lifecycle

Before a provider joins the network they complete a credentialing review. This is a synchronous, in-process service operation, not a Temporal-orchestrated saga. Approval/rejection are only legal from SUBMITTED (the service rejects a decision on any other status); a REJECTED request is terminal; remediation means a new CredentialingRequest, not reopening the old one.

On APPROVED, the service sets Provider.network_status = ACTIVE and stamps activated_at; the decision time is recorded on the request's reviewed_at. network_status (PENDING | ACTIVE | INACTIVE) and CredentialingStatus (SUBMITTED | APPROVED | REJECTED) are Go enums enforced in code, not DB CHECK constraints, defaulting to PENDING / SUBMITTED.

Network status and adjudication

Network status gates claim adjudication: an ACTIVE (in-network) provider is settled differently from an out-of-network one, and a plan with strict network requirements may reject out-of-network claims outright. This network-status → adjudication coupling is the load-bearing fact.

US cost-sharing vocabulary is placeholder

Any "contracted rate vs UCR / deductible + coinsurance" framing is US-style and not the UK model; the concrete cost-sharing rules are not settled. What is real and load-bearing is that network_status feeds the adjudication decision.

Provider directory & booking

• Directory search (full-text / geo) over providers is the intended model, but the event-driven reindex pipeline is not built in the provider service; there is no provider.updated Kafka event and no automatic OpenSearch indexing today. Treat the searchable-directory design as planned.
• Booking lives in the care service: a ProviderSlot is a bookable window (AVAILABLE | BOOKED | CANCELLED) and an Appointment references the provider by locator. Booking flips a slot to BOOKED; cancelling restores AVAILABLE. See Care Pathways.

Invariants

• locator and npi are each unique per database.
• A credentialing decision is legal only from SUBMITTED; APPROVED sets the provider ACTIVE and stamps activated_at; REJECTED is terminal.
• network_status gates whether and how a provider's claims are adjudicated.

Caveats

• Credentialing is synchronous in-process (no Temporal); the provider directory's event-driven OpenSearch reindex is not implemented.
• npi and the US credentialing registries (NPPES/CAQH) are placeholders on this UK platform.
• network_status / credentialing status are code-enforced enums, not DB constraints; integrity is application-level.