# crs4/hl7apy architecture

> Architecture diagram of the GitHub repository crs4/hl7apy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crs4/hl7apy
- Repository: https://github.com/crs4/hl7apy

## Overview

##### Project Type and Purpose
- HL7apy is an open-source Python library (not a client/server web app).
- It provides intuitive handling of HL7 v2 messages: parsing, creation, validation, and a simple MLLP server/client for message transport.

- Core Controller (hl7apy/core.py)
- Entry points: parse_message(), create_message()
- Orchestrates parser, factory, validator, MLLP
- Parser Component (hl7apy/parser.py)
- Transforms raw ER7 strings into an in-memory message tree (composite of segments→fields→datatypes)
- Loads version-specific definitions dynamically
- Factory Component (hl7apy/factories.py)
- Builds message trees programmatically using factory methods
- Data Model Modules
- Base: hl7apy/base_datatypes.py, hl7apy/consts.py
- Version folders (hl7apy/v2_1 … hl7apy/v2_8_2): datatypes, fields, groups, segments, tables
- Validation Component (hl7apy/validation.py)
- Validates message trees against HL7 XSD rules, custom profiles, Z-elements
- MLLP Transport (hl7apy/mllp.py)
- Implements MLLP framing/protocol
- Provides MLLPServer and client for sending/receiving messages over TCP
- Utilities (hl7apy/utils.py + utils/hl7apy_profile_parser)
- Helpers for name resolution, profile parsing, encoding customization
- Support Layers
- examples/ (sample iti_21 client.py & server.py)
- tests/ (unit tests via nose2.cfg)
- docs/ (Sphinx sources, custom theme)
- CI / packaging: .github/workflows, setup.py, tox.ini

##### Relationships and Data Flows
- ER7 string → Parser → Message tree object
- Message tree ← Factory (for programmatic creation)
- Message tree → Validator → ValidationReport
- Message tree → MLLP → External system (hospital applications)
- Core orchestrates the sequence: Parser ↔ Factory ↔ Validator ↔ MLLP
- Data Model modules “plug into” Parser and Factory via dynamic loading

##### Architectural Patterns & Principles
- Modular, version-based folder structure (each HL7 version is a plugin)
- Factory pattern for object creation
- Composite pattern for tree-structured messages
- Single responsibility per module: parsing, building, validating, transporting
- Clear separation of core logic vs. I/O vs. support

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core API Layer
    Core["Core Controller\n(parse_message(), create_message())"]:::processing

    %% Input and Data Flow
    ER7["ER7 Message\n(raw ER7 string)"]:::external
    ER7 -->|feeds| ParserComp
    ParserComp["Parser Component\n(parse(), dynamic version load)"]:::processing
    ParserComp -->|creates| MessageTree["Message Tree\n(composite)"]:::dataModel

    FactoryComp["Factory Component\n(builds message tree)"]:::processing
    FactoryComp -->|builds| MessageTree

    MessageTree -->|validates| ValidatorComp
    ValidatorComp["Validation Component\n(validate())"]:::processing
    ValidatorComp --> ValidationReport["Validation Report"]:::external

    MessageTree -->|transports| MLLPComp
    MLLPComp["MLLP Transport\n(MLLPServer.start(), send())"]:::io
    MLLPComp --> Hospital["Hospital System\n(external)"]:::cylinder

    %% Core Orchestration
    Core -->|orchestrates| ParserComp
    Core -->|orchestrates| FactoryComp
    Core -->|orchestrates| ValidatorComp
    Core -->|orchestrates| MLLPComp

    %% Data Model Modules
    subgraph "Data Model" 
        BaseDT["base_datatypes.py"]:::dataModel
        Consts["consts.py"]:::dataModel
        subgraph "Version Plugins"
            V1["v2_1/"]:::dataModel
            V2["v2_2/"]:::dataModel
            V3["v2_3/"]:::dataModel
            V31["v2_3_1/"]:::dataModel
            V4["v2_4/"]:::dataModel
            V5["v2_5/"]:::dataModel
            V51["v2_5_1/"]:::dataModel
            V6["v2_6/"]:::dataModel
            V7["v2_7/"]:::dataModel
            V8["v2_8/"]:::dataModel
            V81["v2_8_1/"]:::dataModel
            V82["v2_8_2/"]:::dataModel
        end
    end
    ParserComp -.->|loads definitions| BaseDT
    ParserComp -.-> V1
    FactoryComp -.->|uses| BaseDT
    FactoryComp -.-> V1

    %% Utilities
    subgraph "Utilities" 
        Utils["utils.py"]:::support
        Profile["hl7apy_profile_parser/"]:::support
    end

    %% Support Layers
    subgraph "Support"
        Examples["examples/"]:::support
        Tests["tests/"]:::support
        Docs["docs/"]:::support
        CI["CI/CD & Packaging"]:::support
    end

    Examples -->|includes| Client["iti_21/client.py"]:::support
    Examples -->|includes| Server["iti_21/server.py"]:::support
    CI --> PushRelease[".github/workflows/push_release.yml"]:::support
    CI --> RunTests[".github/workflows/run_tests.yml"]:::support
    CI --> Setup["setup.py"]:::support
    CI --> Tox["tox.ini"]:::support

    %% Click Events
    click Core "https://github.com/crs4/hl7apy/blob/develop/hl7apy/core.py"
    click ParserComp "https://github.com/crs4/hl7apy/blob/develop/hl7apy/parser.py"
    click FactoryComp "https://github.com/crs4/hl7apy/blob/develop/hl7apy/factories.py"
    click ValidatorComp "https://github.com/crs4/hl7apy/blob/develop/hl7apy/validation.py"
    click MLLPComp "https://github.com/crs4/hl7apy/blob/develop/hl7apy/mllp.py"
    click BaseDT "https://github.com/crs4/hl7apy/blob/develop/hl7apy/base_datatypes.py"
    click Consts "https://github.com/crs4/hl7apy/blob/develop/hl7apy/consts.py"
    click V1 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_1/"
    click V2 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_2/"
    click V3 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_3/"
    click V31 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_3_1/"
    click V4 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_4/"
    click V5 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_5/"
    click V51 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_5_1/"
    click V6 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_6/"
    click V7 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_7/"
    click V8 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_8/"
    click V81 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_8_1/"
    click V82 "https://github.com/crs4/hl7apy/tree/develop/hl7apy/v2_8_2/"
    click Utils "https://github.com/crs4/hl7apy/blob/develop/hl7apy/utils.py"
    click Profile "https://github.com/crs4/hl7apy/tree/develop/utils/hl7apy_profile_parser/"
    click Examples "https://github.com/crs4/hl7apy/tree/develop/examples/"
    click Client "https://github.com/crs4/hl7apy/blob/develop/examples/iti_21/client.py"
    click Server "https://github.com/crs4/hl7apy/blob/develop/examples/iti_21/server.py"
    click Tests "https://github.com/crs4/hl7apy/tree/develop/tests/"
    click Docs "https://github.com/crs4/hl7apy/tree/develop/docs/"
    click PushRelease "https://github.com/crs4/hl7apy/blob/develop/.github/workflows/push_release.yml"
    click RunTests "https://github.com/crs4/hl7apy/blob/develop/.github/workflows/run_tests.yml"
    click Setup "https://github.com/crs4/hl7apy/blob/develop/setup.py"
    click Tox "https://github.com/crs4/hl7apy/blob/develop/tox.ini"

    %% Styles
    classDef processing fill:#9f6,stroke:#333,stroke-width:1px
    classDef dataModel fill:#6cf,stroke:#333,stroke-width:1px
    classDef io fill:#f90,stroke:#333,stroke-width:1px
    classDef support fill:#ccc,stroke:#333,stroke-width:1px
    classDef external fill:#fff,stroke:#333,stroke-width:1px
    classDef cylinder fill:#fff,stroke:#333,stroke-width:1px,shape:cylinder
```
