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](https://typer.tiangolo.com/) for the CLI, providing better error messages, colored output, and shell completion support.

Basic conversion (uses defaults from mapping_config.json):
```bash
python3 fhir_to_pad_converter.py -i Input.json -o .
```

With XSD validation:
```bash
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:
```bash
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:
```bash
python3 fhir_to_pad_converter.py --help
```

### Shell Completion (Optional)

Typer provides automatic shell completion. To install:

**Bash**:
```bash
python3 fhir_to_pad_converter.py --install-completion bash
source ~/.bashrc
```

**Zsh**:
```bash
python3 fhir_to_pad_converter.py --install-completion zsh
source ~/.zshrc
```

**Fish**:
```bash
python3 fhir_to_pad_converter.py --install-completion fish
source ~/.config/fish/config.fish
```

After installation, you can use tab completion:
```bash
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**:
```json
{
  "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:
```bash
python3 fhir_to_pad_converter.py -i input.json -o . --header-cfg custom_header.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)
  - `typer[all]` (Modern CLI framework with colored output)
- **Built-in**: `xml.etree.ElementTree`, `json`, `datetime`, `pathlib`, `logging`

Install dependencies:
```bash
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.