HealthData.Interop.Fhir

📢 Free Resource

Building FHIR interoperability? I made a free checklist of the 12 pitfalls teams hit before Cures Act certification.

🏥 More Healthcare IT Projects by the Author

Two independent healthcare IT projects built by the author. They are not built on top of this library — they simply live in the same healthcare interoperability space.

• Clinic FHIR Server — a multi-tenant FHIR R4 server for clinics and community health centers: tenant-isolated FHIR storage, role-based access control, audit logging, and PHI encryption. Live demo ↗
• XBridge — a Prior Authorization toolkit that validates X12 278 transactions against payer Companion Guide rules and converts between X12 and FHIR R4, running 100% in your local browser. Live demo ↗

Installation

Install the HealthData.Interop.Fhir NuGet package into your .NET project:

# Via .NET CLI
dotnet add package HealthData.Interop.Fhir

# Via Package Manager Console
Install-Package HealthData.Interop.Fhir

# Via Paket
paket add HealthData.Interop.Fhir

Quick Start

Get up and running with FHIR R4 client operations:

using HealthDataInteropSharedLibrary.BasicClient;
using HealthDataInteropSharedLibrary.ResourceValidator;

var client = new FhirBasicService("https://your-fhir-server/fhir");

// Search patients by name
var results = await client.SearchPatientsByNameAsync("Doe");
foreach (var patient in results)
{
    Console.WriteLine($"Patient: {FhirBasicService.FormatPatientName(patient)}");
}

// Create a patient
var created = await client.CreatePatientAsync(
    new[] { "John" }, "Doe", "male", "1985-01-15", "MRN-1234");

// Validate a Patient resource against the R4 specification
var validator = new ResourceValidationService();
if (results.Count > 0)
{
    bool valid = validator.Validate(results[0]);
    Console.WriteLine(valid ? "Valid against FHIR R4." : "Validation found issues.");
}

What This Project Demonstrates

This repository is an application-layer toolkit and reference implementation for HL7 FHIR R4 interoperability on .NET, built on the Firely .NET SDK. It does not replace a FHIR server, and it does not by itself provide certified HIPAA or ONC compliance. It is a set of working patterns you can read, run, and adapt:

• FHIR client patterns — Patient create/search and chained-parameter search with _include/_revinclude, wrapped in small testable services on top of the Firely .NET SDK.
• FHIR resource validation — Firely SDK validation against the FHIR R4 specification, plus a US Core profile-declaration check (Meta.Profile) — not full US Core IG conformance.
• CSV → FHIR ETL — legacy CSV to Patient mapping with idempotent upserts (search-then-Conditional-PUT), compile-time mapping via Mapperly.
• SMART on FHIR — OAuth2/OIDC client-credentials flow with token caching, plus a SMART-style ETL import.
• Local LLM normalization — a local model (Ollama) normalizes messy records, with deterministic guardrails rejecting invalid output; designed for local inference without sending data to a cloud LLM.
• HIPAA Security Rule–oriented examples — RBAC, consent validation, audit logging, PHI masking (45 CFR §164.312-style controls) — illustrative examples, not a compliance certification.
• Data drift detection — read-only reconciliation between a legacy source and the synced FHIR copy.

It is intended as a reference implementation and educational resource — see the License section below.

Modules & What They Demonstrate

Each numbered module is a small console app exercising one scenario:

API Reference

BasicClient.FhirBasicService

// Constructor: FHIR server base URL
var service = new FhirBasicService("https://your-fhir-server/fhir");

// Key methods:
var patients = await service.SearchPatientsByNameAsync("Doe");
var created  = await service.CreatePatientAsync(
    new[] { "John" }, "Doe", "male", "1985-01-15", "MRN-1234");
Console.WriteLine(FhirBasicService.FormatPatientName(patients[0]));

ResourceValidator.ResourceValidationService

var validator = new ResourceValidationService();
bool isValid = validator.Validate(patient);
var issues = validator.GetValidationIssues(patient);

ResourceValidator.UsCoreConformanceChecker

// Check if a Patient resource declares a US Core profile
var result = UsCoreConformanceChecker.CheckPatientConformance(patient);
Console.WriteLine(result.IsUsCoreConformant); // true or false

// Ensure Patient has a US Core profile in Meta
bool added = UsCoreConformanceChecker.EnsureUsCoreProfile(patient);

Compliance.HipaaComplianceOrchestrator

// RBAC PHI access check (8 roles) — synchronous, returns bool
var orchestrator = new HipaaComplianceOrchestrator();
bool allowed = orchestrator.ExecutePhiAccessRequest(
    userId: "u-1001",
    role: FhirUserRole.Physician,
    ipAddress: "10.0.0.5",
    patientId: "123",
    accessPurpose: "Clinical review");

// PHI encryption service (AES-256-GCM; supply your own 32-byte key)
var key = new byte[32]; // key management is your responsibility
var phi = new PhiEncryptionService(key);
var (ciphertext, nonce, tag) = phi.Encrypt(sensitiveData);
var plaintext = phi.Decrypt(ciphertext, nonce, tag);

// Audit log
AuditLog.Record(
    userId: "u-1001", role: "Physician", ipAddress: "10.0.0.5",
    resourceType: "Patient", resourceId: "123", action: "READ");

Etl.EtlPipelineService

// CSV to FHIR Patient mapping pipeline
var mapper = new FhirPatientMapper(addTestDataTag: true, testNameMarkers: true);
var service = new EtlPipelineService(fhirClient, mapper);
var (created, updated) = await service.RunAsync("data/legacy_patients.csv");

AIDataValidator.AiValidatorService

// Requires Ollama running locally with the llama3 model.
// The AI provider is injected as a plain Func<string, Task<string>>,
// so you can point it at any local model endpoint.
var validator = new AiValidatorService(prompt => OllamaChatAsync(prompt));
var patient = await validator.ProcessRawRecordAsync("Mmale, Jhon Doe, 1990-05-14");

Security Notice

License & Disclaimer

This project is licensed under the MIT License.

🙌 Support this work

If this work is helpful to you, feel free to send a small gift — it helps support my work and keep the project maintained.

Alipay Scan with Alipay to pay

Venmo or open Venmo ↗

PayPal

PayPal Click to open PayPal ↗

💜

GitHub Sponsors Click to open GitHub Sponsors ↗