fhir2padnext/GEMINI.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

Basic conversion:
```bash
python3 fhir_to_pad_converter.py \
  --input-json Input.json \
  --output-xml output.xml
```

With validation and report:
```bash
python3 fhir_to_pad_converter.py \
  --input-json samples/fhir/sample_1/226844_1240059013-KaBr.json \
  --output-xml output.xml \
  --report-json report.json \
  --pad-xsd specs/padnext/padx_adl_v2.12.xsd
```

With header configuration:
```bash
python3 fhir_to_pad_converter.py \
  --input-json Input.json \
  --output-xml output.xml \
  --header-cfg header_config.json
```

### Validate PADneXt XML

Single file:
```bash
python3 validate_padnext.py \
  samples/padnext/sample_1/00209999_20250805_ADL_000087_padx.xml \
  specs/padnext/padx_adl_v2.12.xsd
```

Multiple files:
```bash
python3 validate_padnext.py \
  file1.xml schema1.xsd \
  file2.xml schema2.xsd
```

## Dependencies

- **Python 3.11+**
- **Required**: `lxml` (XSD validation), `jsonschema` (FHIR validation)
- **Built-in**: `xml.etree.ElementTree`, `argparse`, `json`, `datetime`, `random`

Install dependencies:
```bash
pip3 install lxml jsonschema
```

## 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.