FHIR Lessons

Hands-on lessons for learning HL7 FHIR (Fast Healthcare Interoperability Resources) — from spinning up a local server to creating, linking, and validating clinical resources, building care plans, and working with bulk data operations.

What's Inside

FHIRLessons/
├── FHIR-Learning-Plan.md                 # Full 16-step execution plan
├── lessons/                              # 18 deep-dive lesson files
│   ├── README.md                         # Lesson index with progress tracking
│   ├── 01 - 03                           # Foundations (server, APIs, security)
│   ├── 04 - 05                           # Patient (create, update demographics)
│   ├── 06 - 09                           # Clinical resources (encounters, observations, conditions, procedures)
│   ├── 10 - 11                           # Implementation guides & validation
│   ├── 12 - 13                           # Questionnaires & patient-reported outcomes
│   ├── 14 - 16                           # Care planning (PlanDefinition, CarePlan, lifecycle)
│   └── 17 - 18                           # Data operations (bundles, bulk export)
└── resources/
    ├── docker-compose.yml                # HAPI FHIR server + Postgres + US Core IG
    └── dotnet/                           # .NET Firely SDK project
        ├── src/FhirLearning.Services/    # 16 service classes
        └── tests/FhirLearning.Tests/     # 156 tests across 16 test files (Steps 1-16)

Getting Started

1. Start the FHIR server:

   cd resources
   docker compose up -d

   First startup takes ~2 minutes (downloads US Core IG from Simplifier).

2. Verify the server is running:

   curl http://localhost:8080/fhir/metadata

3. Run the .NET tests:

   cd resources/dotnet
   dotnet test

4. Read FHIR-Learning-Plan.md for the full walkthrough, and study lessons/ for deep dives.

Lessons

#	Lesson	Topic
01	Resources & Encounters	FHIR resource types, Encounters, how resources link together
02	FHIR Servers & APIs	What a FHIR server provides, REST operations, search
03	FHIR Security & SMART	OAuth, SMART on FHIR, production security layers
04	Create Patient (US Core)	Patient resource, US Core profile, extensions, identifiers
05	Update Demographics	PUT vs PATCH, versioning, _history, CodeableConcept
06	Encounters Deep Dive	Encounter types, status lifecycle, class codes, period
07	Observations Deep Dive	value[x] types, LOINC, components, reference ranges, categories
08	Conditions Deep Dive	Diagnoses, clinical/verification status, SNOMED + ICD-10, evidence
09	Procedures Deep Dive	Procedures, performed[x], reasonReference, CPT, complications
10	Implementation Guides	US Core IG, StructureDefinitions, ValueSets, STORE_AND_INSTALL
11	Validation Against US Core	$validate, OperationOutcome, terminology services, VSAC
12	Questionnaires (PROM)	Questionnaire resource, item types, answer options, PROMs
13	QuestionnaireResponse	Capturing patient answers, linkId matching, answer types
14	PlanDefinition & ActivityDefinition	Care protocols, actions, ActivityDefinition kinds, timing
15	CarePlan — $apply	Patient-specific plans from templates, activity mapping
16	Activity Schedule & Lifecycle	Status updates, workflow simulation, plan completion
17	Bundle Transactions	Atomic multi-resource operations, urn:uuid references, batch
18	Bulk Data Export	$export concept, $everything, paginated search, NDJSON

See lessons/README.md for full progress tracking, .NET services, and test details.

Stack

Component	Technology
FHIR Server	HAPI FHIR (Docker) with Postgres
FHIR Version	R4
Implementation Guide	US Core 6.1.0
SDK	.NET with Firely SDK
Tests	xUnit

Prerequisites

• Docker Desktop installed and running
• .NET 10 SDK (or later)
• A REST client (Postman, VS Code REST Client, or curl)