fhir2padnext/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

FHIR_PAD is a Python-based converter that transforms FHIR JSON bundles into PADneXt 2.12 XML format (German healthcare billing standard). The converter validates both input FHIR data and output PAD XML, producing detailed diagnostic reports.

Core Architecture

Main Components

1. fhir_to_pad_converter.py - Primary converter with validation pipeline

   • Validates FHIR JSON bundles (schema-based or structural checks)
   • Groups FHIR resources by patient/encounter or by Claim resource.
   • Maps FHIR resources to PAD billing positions
   • Generates PADneXt 2.12 compliant XML
   • Validates output against XSD schemas
   • Produces JSON diagnostic reports
   • Outputs declarative AUF (order) information to the console.

2. validate_padnext.py - Standalone PADneXt XML validator

   • Validates PADneXt 2.12 ADL/AUF XML files against XSD schemas
   • Accepts multiple XML/XSD pairs for batch validation

3. utils.py - Utility functions

   • Contains helper functions for date parsing, reference extraction, and other common tasks.

4. validation.py - Validation framework

   • Provides a framework for semantic and business rule validation of FHIR data.

Data Flow

FHIR JSON Bundle → Validation → Resource Grouping → Mapping → PAD XML Generation → XSD Validation → Report

Resource Grouping: If Claim resources are present, FHIR entries are grouped by (patient_id, claim_id). Otherwise, they are grouped by (patient_id, encounter_id). Each group becomes one <Rechnung> (invoice) in the PAD output.

Resource Mapping:

• If a Claim resource is present, its item entries are mapped to <goziffer> positions.
• If no Claim is present, the following FHIR resources are converted to billing positions:
  • Observation, MedicationAdministration, Procedure, ServiceRequest, DiagnosticReport
• ExplanationOfBenefit resources are used to enrich the JSON report with adjudication details.

Date Handling: Effective dates extracted from FHIR fields (effectiveDateTime, issued, authoredOn, date, meta.lastUpdated) determine the zeitraum (time period) for each billing case.

Common Commands

Convert FHIR to PAD XML

Note: The converter now uses Typer for the CLI, providing better error messages, colored output, and shell completion support.

Basic conversion (uses defaults from mapping_config.json):

python3 fhir_to_pad_converter.py -i Input.json -o .

With XSD validation:

python3 fhir_to_pad_converter.py \
  -i samples/fhir/sample_1/226844_1240059013-KaBr.json \
  -o . \
  --pad-xsd specs/padnext/padx_adl_v2.12.xsd

With verbose output:

python3 fhir_to_pad_converter.py -i Input.json -o . --verbose

# Or short form:
python3 fhir_to_pad_converter.py -i Input.json -o . -v

Get help:

python3 fhir_to_pad_converter.py --help

Shell Completion (Optional)

Typer provides automatic shell completion. To install:

Bash:

python3 fhir_to_pad_converter.py --install-completion bash
source ~/.bashrc

Zsh:

python3 fhir_to_pad_converter.py --install-completion zsh
source ~/.zshrc

Fish:

python3 fhir_to_pad_converter.py --install-completion fish
source ~/.config/fish/config.fish

After installation, you can use tab completion:

python3 fhir_to_pad_converter.py --input-<TAB>
# Shows: --input-json

Configuration

Unified Configuration File (mapping_config.json)

The converter uses a single configuration file (mapping_config.json) that contains:

1. Header configuration - Practice/billing information (sender, recipient, etc.)
2. Resource mapping - How FHIR resources map to PADneXt billing positions

Key Benefits:

• ✅ Single file to manage
• ✅ Header defaults automatically loaded
• ✅ Easy to version control
• ✅ No need for separate --header-cfg flag

Structure:

{
  "header": {
    "empfaenger_name": "AOK Berlin",
    "leistungserbringer_name": "Schmidt",
    "rechnungsersteller_kundennr": "PRX123456",
    ...
  },
  "resources": {
    "Observation": { ... },
    "Procedure": { ... }
  }
}

Customization:

1. Edit mapping_config.json directly
2. Update header section with your practice details
3. No command-line changes needed - automatically loaded

Override: You can still use --header-cfg to override the defaults:

python3 fhir_to_pad_converter.py -i input.json -o . --header-cfg custom_header.json

Validate PADneXt XML

Single file:

python3 validate_padnext.py \
  samples/padnext/sample_1/00209999_20250805_ADL_000087_padx.xml \
  specs/padnext/padx_adl_v2.12.xsd

Multiple files:

python3 validate_padnext.py \
  file1.xml schema1.xsd \
  file2.xml schema2.xsd

Dependencies

• Python 3.11+
• Required:
  • lxml (XSD validation)
  • jsonschema (FHIR validation)
  • typer[all] (Modern CLI framework with colored output)
• Built-in: xml.etree.ElementTree, json, datetime, pathlib, logging

Install dependencies:

pip3 install -r requirements.txt
# Or manually:
pip3 install lxml jsonschema 'typer[all]'

Directory Structure

samples/
  fhir/sample_1/       - Example FHIR JSON bundles
  fhir/sample_2/       - Example FHIR JSON bundle with Claim resource
  padnext/sample_1/    - Example PADneXt XML outputs (ADL/AUF)
specs/
  padnext/             - PADneXt 2.12 XSD schemas and documentation
    padx_adl_v2.12.xsd - ADL (billing) schema
    padx_auf_v2.12.xsd - AUF (order) schema
    padx_basis_v2.12.xsd - Base types
    padx_enums_v2.12.xsd - Enumerations
    documentation_de/  - German specification PDFs

Key Implementation Details

PAD Namespace

All PAD XML elements use namespace http://padinfo.de/ns/pad

Claim-driven Conversion

If a FHIR Claim resource is present in the input bundle, it is used as the primary source of information for generating the PADneXt <Rechnung>. The Claim.item entries are converted to billing positions, and information about the provider, insurer, and patient is extracted from the Claim and its referenced resources.

Header Configuration

Header fields (billing entity, service provider, recipient) can be configured via --header-cfg JSON. If a Claim resource is present, the information from the Claim will override the header_cfg.

Validation Modes

• FHIR: JSON Schema validation (if schema provided) or structural checks. A new validation framework in validation.py allows for custom semantic and business rule validation.
• PAD: XSD validation (if XSD provided) or well-formedness checks.

Report Structure

JSON reports contain:

• input.schema_validation_ok - FHIR validation status
• input.stats - Resource counts, date ranges, warnings, and ExplanationOfBenefit stats.
• output.schema_validation_ok - PAD validation status
• output.stats - Invoice counts, position counts, warnings.
• validation_warnings - A list of warnings from the custom validation framework.

AUF Log Output

The converter prints declarative information to the console that would be contained in a pad_auf.xml file, such as sender, recipient, and the number of invoices.

Important Functions

• group_entries() - Groups FHIR resources by (patient_id, claim_id) if a Claim is present, otherwise by (patient_id, encounter_id).
• claim_item_to_position() - Maps a Claim.item to a PAD billing position.
• claim_to_rechnung_header() - Extracts header information from a Claim resource.
• resource_to_position() - Maps other FHIR resources to a PAD billing position (fallback).
• build_pad_xml() - Main XML generation logic, now with support for Claim-driven conversion.
• run_validation() (in validation.py) - Runs all custom validation checks.
• find_resource_by_ref() (in utils.py) - Helper function to resolve references within a FHIR bundle.