National Health Workforce Registry
Volunteer project Public health dataA governed registry, real-time API, public reporting interface, and authenticated operations portal for a national health regulator. The design preserves official facility identity, labels synthetic practitioner and staffing records, and refuses to fill source-data gaps with plausible values.
Evidence and publication boundary
The figures below come from the reviewed project repository and its sealed source manifest, requirements traceability, data contracts, automated checks, and release documentation.
Verified scope
8,627 Official facility identity records in the sealed directory snapshot, each keyed to a permanent national identifier.Reviewed matches
1,132 High-confidence external OSM location matches kept in a separate evidence-governed overlay, with field verification pending.Traced scope
48 Numbered regulator requirements evaluated with delivered, partial, handover, or external-dependency status recorded.Evidence and confidentiality note. The regulator’s name, private repository, protected administrative surfaces, internal documentation, credentials, and live URL are not published here. Of 8,627 official facilities, 7,495 remain explicitly unmapped rather than receiving inferred points. Coordinates are external matches, not official or field-verified locations, and remain separate from the facility identity record.
The problem
A national regulator needed one system for practitioner registration, licensing, employment history, workforce reporting, facility search, and operational administration. The supplied specification covered 48 numbered requirements across onboarding, external validation, reporting, and mapping.
The authoritative facility source answered only part of that brief. It supplied official identity and administrative hierarchy, but not coordinates, level of care, ownership, operational status, approved posts, staffing norms, or capacity. Several requested dashboard measures depended on exactly those absent fields.
The central design decision was to show an explicit gap instead of inventing an input. Features that lacked a defensible source were marked partial, held for handover, or retired until the responsible data owner could supply the missing evidence.
My contribution
I scoped and directed the end-to-end delivery: translating the regulator’s specification into data contracts, implementation tasks, acceptance criteria, privacy controls, and release gates across the database, API, public interface, and administrative portal.
I reviewed implementation outputs, tested failure modes, reconciled the facility source, documented unsupported requirements, and built the traceability and operating procedures needed for another team to inspect, deploy, refresh, and recover the system.
Data boundaries
- Official facility identity. Facility identifiers, names, source timestamp, and administrative hierarchy come from the sealed national facility directory. Those records remain the identity authority.
- Reviewed location evidence. Coordinates are not supplied by the official directory. They live in a separate, versioned overlay keyed to the exact facility identifier, with source evidence, review, withdrawal, and audit history. Unverified facilities remain unmapped.
- Synthetic practitioner data. Demo practitioners, registrations, licences, employments, lifecycle events, and facility assignments are synthetic or modelled. Every person-linked demo record carries that status.
- Derived public reporting. Staffing snapshots and public aggregates are derived from the synthetic assignments. They demonstrate the reporting workflow; they are not observed national workforce totals.
The separation is structural, not a disclaimer added at the end. Official facility records, reviewed coordinate evidence, synthetic people, and derived reports have different provenance and cannot silently become one another.
Architecture
Tools used
Controls built into the product
- No inferred locations. A facility without reviewed coordinate evidence remains visibly unmapped rather than being placed at a district centroid.
- No mixed releases. Public reads open only when the database, control file, API, web deployment, and sealed source hashes identify the same reviewed release.
- No identifiable public small cells. Groups of one to four people are suppressed, public roles cannot read practitioner records, and aggregate updates are time-quantized.
- No self-approval. Staffing and coordinate changes use scoped maker-checker workflows that revalidate current authority before committing an atomic change.
- No silent requirement substitution. Measures that need unavailable official inputs remain blocked or retired, with the reason preserved in the traceability register.
A release is an operating procedure
Replacing the national facility catalogue is treated as a governed migration, not a file upload. The runbook verifies the certified source, rehearses the replacement in isolation, creates an encrypted backup, proves that backup can be restored, previews and certifies the candidate, closes public readiness, applies the release, runs smoke checks, and only then reopens reads.
Rollback deliberately leaves the system closed. Reopening a prior release requires a separate recertification so that a quick recovery cannot bypass the same controls expected of a new deployment.
Scheduled refreshes stage and validate a complete candidate before promotion. Source downtime, network errors, or suspicious semantic changes leave the last reviewed catalogue serving unchanged.
What was delivered
- A provenance-bound facility catalogue and paginated directory based on the official source snapshot.
- A MongoDB registry with effective-dated practitioner, licence, employment, discipline, document, and audit records for the synthetic demonstration population.
- Public workforce reporting with disclosure controls, district views, map behavior that distinguishes mapped from unmapped facilities, and explicit unavailable states.
- An authenticated, role-, capability-, and scope-aware operations portal for registry administration, facility data, staffing workflows, reports, and governed account management.
- Requirements traceability, source and import contracts, deployment documentation, automated verification, a data-request register, and fail-closed replacement and rollback procedures.
Limits and next dependencies
The practitioner population is synthetic pending formal data-sharing approval. The dashboard therefore demonstrates registry and reporting behavior, not the real distribution, employment, or licensure status of the country's workforce.
Facility coordinates are an external, separately governed overlay and remain incomplete and subject to field verification. The map is not presented as nationwide point coverage, and the official facility master remains coordinate-free.
Vacancy, staffing-norm, facility-capacity, and rural-versus-urban measures need official inputs that were not present in the reviewed source. Those outputs remain unavailable rather than being populated from legacy or inferred values.
Production continuation depends on the regulator’s approvals and operating ownership after handover, along with credentials for government integrations, data stewardship, independent coordinate review, and backup retention.
Want this for your business?
Through Scott Campbell Consulting I take on data cleanup, dashboards and recurring reporting for small businesses and agencies.