fi-fhir docs

fi-fhir User Guide

Welcome to fi-fhir, a format-agnostic healthcare integration platform that transforms legacy formats (HL7v2, CSV, EDI X12, CDA/CCDA) into semantic events and routes them through configurable workflows.

Quick Links

I want to...	Read...
Parse my first HL7v2 message	Getting Started
Understand the 3-phase pipeline	Core Concepts
Configure a source profile	Source Profiles
Route events to multiple destinations	Workflow Configuration
Test workflows without side effects	Workflow Configuration
Load standard terminologies (LOINC, RxNorm)	Terminology Management
Map local codes to standard terminologies	Terminology Management
Generate FHIR resources	FHIR Output
Get AI-powered warning explanations	LLM-Powered Features
Generate workflows from natural language	LLM-Powered Features
Search terminology by meaning	LLM-Powered Features
Try it in the browser	Playground Tutorial
Know what the browser playground runs, and what needs the IDE	Browser Playground
Find my way around the IDE	Mapping Studio (IDE)
Click through the real IDE without installing anything	Hosted demo: the IDE shell with a preview-only identity and no database; HL7 Preview works, every other surface shows its honest "not available on this deployment" state, nothing is stored
Define a source or destination connection	Connections
See what this replica is actually running	Connections
Pull real messages from a source into a session	Connections
Run the batch-to-hospital demo on the LAN environment	End-to-end demo
Check what the engine admitted and delivered	Verification

What is fi-fhir?

fi-fhir addresses a core problem in healthcare integration: users think in workflow terms, but tools require format-specific knowledge.

Instead of writing code that references PID.3.1 or OBX.5, you work with semantic events like patient_admit and lab_result. The library handles format parsing, field mapping, validation, and routing automatically.

Key Features

Multi-format parsing: HL7v2, CSV/flatfiles, EDI X12, CDA/CCDA
Profile-driven: Each data feed gets its own configuration
Semantic events: Work with business concepts, not format details
Workflow DSL: YAML-based routing with CEL expression filters
FHIR R4 output: US Core profile mapper with 24+ resources
Production-ready: Retry, circuit breaker, observability built-in

Architecture Overview

Input Formats          Semantic Layer           Output/Actions
─────────────         ────────────────         ──────────────
HL7v2    ──┐          ┌─────────────┐          ┌─> FHIR API
Flatfile ──┼──────────┤ Canonical   ├──────────┼─> REST Webhook
EDI X12  ──┤          │ Event Model │          ├─> Database
CDA/CCDA ──┤          └─────────────┘          └─> Message Queue
FHIR     ──┘

Prerequisites

For CLI usage: Go 1.21+ or Docker
For TypeScript SDK: Node.js 18+
For Playground: Just a web browser!

Next Steps

If you're new to fi-fhir, start with Getting Started for a hands-on tutorial.

If you prefer to learn by exploring, try the Playground Tutorial to experiment in your browser.