Build your bridge to FHIR.

Project status

FHIR at Will is the project; fhirbridge is its Python package and HTTP service. The current platform provides an authenticated FHIR R4 validation service and the infrastructure required to operate it safely.

Available today

• FHIR R4 resource and Bundle validation
• Profile checks against preloaded implementation guides
• Terminology validation and ConceptMap translation
• FHIRPath invariants and configurable plausibility rules
• FHIR OperationOutcome and native JSON reports
• API-key authentication, tenant isolation, metrics, and tracing hooks

Planned

• Narrative and document ingestion
• BYOK/BYOM provider routing and LLM calls
• Clinical extraction, assembly, repair, fidelity, and coverage scoring
• Human review queues and delivery workflows

Quickstart with Docker

You need Docker with Compose v2, at least 4 GB of available memory, and network access during the validator image build.

1. Configure the stack

Clone the main project, then create your environment file.

git clone https://github.com/Safwanmahmoud/FHIR-It-Will.git
cd FHIR-It-Will
cp .env.example .env

On Windows PowerShell, use Copy-Item .env.example .env. Set distinct owner and application database passwords:

POSTGRES_PASSWORD=choose-an-owner-password
APP_DB_PASSWORD=choose-a-different-app-password

2. Bootstrap and start

docker compose --profile setup run --rm bootstrap
docker compose up -d
docker compose ps

3. Confirm readiness

curl http://localhost:8000/livez
curl http://localhost:8000/readyz
curl http://localhost:8000/version

The API runs at http://localhost:8000. Interactive OpenAPI documentation is available at /docs.

Validate a resource

Every compute endpoint requires a Bearer API key. A non-conformant resource returns a successful validation report; it is not treated as an HTTP transport error.

curl -X POST http://localhost:8000/v1/validate \
  -H "Authorization: Bearer fhirb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "resource": {
      "resourceType": "Patient",
      "id": "example",
      "name": [{"family": "Shaw", "given": ["Amy"]}],
      "gender": "female"
    }
  }'

Requests may select profiles, validation layers, severity overrides, and terminology-check limits. A bare resource is also accepted with Content-Type: application/fhir+json.

API reference

Health and discovery

Validation and terminology

The validation cascade

Every report includes all eight layers. A layer that did not run is explicitly marked skipped or not_applicable; absence never looks like a pass.

Architecture

Clients authenticate to a FastAPI service. The service orchestrates typed FHIR models, the private HL7 validator sidecar, a terminology service, versioned plausibility rules, routing decisions, and tenant-aware PostgreSQL storage.

• The API uses a least-privileged database role subject to row-level security.
• The validator remains private because it has no authentication and can fetch referenced resources.
• Readiness fails closed when a required verification dependency is unavailable.
• JSON logs, Prometheus metrics, and OpenTelemetry hooks support operations.

Configuration

Production mode rejects insecure transport and unsafe dependency defaults. For the complete settings reference, see .env.example in the main repository.

Security and privacy

• API keys are stored as Argon2id hashes.
• Tenant-scoped tables enforce PostgreSQL row-level security.
• Submitted validation resources are scored and dropped rather than persisted.
• Validation responses use Cache-Control: no-store.
• Logs record decisions and counts, not resource bodies or clinical values.
• Secrets and known sensitive fields pass through centralized redaction.

Roadmap

Development

Python 3.12 and uv are the supported development path.

uv sync
uv run pytest -q -m "not integration"
uv run ruff check .
uv run ruff format --check .
uv run mypy

Integration tests require real PostgreSQL, Redis, validator, and terminology dependencies:

uv run pytest -m integration

See the main repository → for contributing rules, full API examples, and source layout.