# headwayio/edi architecture

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

- Interactive diagram: https://gitdiagram.com/headwayio/edi
- Repository: https://github.com/headwayio/edi

## Overview

##### Project type and purpose
- This is a Rust library (“crate”) named `edi` that provides parsing of X12 EDI documents into in‐memory Rust structs.
- Key use cases: strict or loose parsing of EDI text streams, rich error reporting, and serde‐compatible serialization/deserialization.

##### File structure
- Top‐level files:
- Cargo.toml, LICENSE.md, README.md, .gitignore, CI config
- `src/` modules:
- tokenizer.rs – breaks raw input into tokens (elements, segments)
- edi_document.rs, interchange_control.rs, functional_group.rs, transaction.rs, generic_segment.rs – data‐model definitions
- edi_parse_error.rs – error types and verbose error reporting
- lib.rs – public API (`parse` and `loose_parse`) + module re-exports
- `resources/schemas.csv` – optional metadata (schemas) for future validation
- `examples/` – usage samples of API
- `tests/` – unit and validation tests

##### README for additional insights
- Two parser entry points: `parse` (strict) and `loose_parse` (lenient)
- Output type: `EdiDocument` that implements `Serialize`/`Deserialize` via serde
- Limitations: only standard X12, no transaction‐specific schemas, no loop detection

##### Main components
a. Input layer
- Raw EDI text file/stream (e.g., `sample_edi.txt` in examples)
b. Tokenizer
- Reads raw text → produces tokens (segment separators, element data)
c. Parser
- Two entry functions (`parse`, `loose_parse`)
- Drives state machine across tokens to build hierarchical structs
d. Data Model
- `EdiDocument` – root container
- `InterchangeControl` – envelopes
- `FunctionalGroup` – groups of transactions
- `Transaction` – individual transaction sets
- `GenericSegment` – a catch‐all segment representation
e. Error Handling
- `EdiParseError` – rich error type carrying segment context
f. Serialization/Deserialization
- serde integration for converting `EdiDocument` to/from JSON, etc.
g. Resources (optional)
- `schemas.csv` for future mapping/schema validation

##### Relationships and interactions
- Raw input feeds into the Tokenizer
- Tokenizer outputs a stream of tokens for the Parser
- Parser functions orchestrate token consumption to instantiate Data Model objects
- On parse failure, Parser returns `EdiParseError` with context
- On success, `EdiDocument` is returned and can be serialized via serde
- Example code and tests drive both Tokenizer and Parser to validate functionality

##### Architectural patterns and design principles
- Single Responsibility: tokenizer, parser, data model, and error handling are decoupled modules
- Functional style: pure functions `parse`/`loose_parse` return a Result wrapping either a model or an error
- Extensibility: public data model with `pub` fields, resources file for future schema support
- Zero-copy serde serialization for performance

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Raw EDI Input"]:::external
    Tokenizer["Tokenizer"]:::internal
    Parser["Parser\n(parse()/loose_parse())"]:::internal
    subgraph "Data Model"
        DM1["EdiDocument"] 
        DM2["InterchangeControl"]
        DM3["FunctionalGroup"]
        DM4["Transaction"]
        DM5["GenericSegment"]
    end
    Error["EdiParseError"]:::error
    Serializer["Serializer\n(serde conversion)"]:::serializer
    Resources["Schemas.csv"]:::resource
    Examples["Examples"]:::external
    Tests["Tests"]:::external

    A -->|feeds into| Tokenizer
    Tokenizer -->|token stream| Parser
    Parser -->|builds| DM1
    Parser -->|builds| DM2
    Parser -->|builds| DM3
    Parser -->|builds| DM4
    Parser -->|builds| DM5
    Parser -->|on failure| Error
    Parser -->|optionally validates| Resources
    DM1 -->|serialize/deserialize| Serializer
    Examples -->|drives| Tokenizer
    Examples -->|drives| Parser
    Tests -->|validates| Tokenizer
    Tests -->|validates| Parser

    click A "https://github.com/headwayio/edi/blob/master/examples/sample_edi.txt"
    click Tokenizer "https://github.com/headwayio/edi/blob/master/src/tokenizer.rs"
    click Parser "https://github.com/headwayio/edi/blob/master/src/lib.rs"
    click DM1 "https://github.com/headwayio/edi/blob/master/src/edi_document.rs"
    click DM2 "https://github.com/headwayio/edi/blob/master/src/interchange_control.rs"
    click DM3 "https://github.com/headwayio/edi/blob/master/src/functional_group.rs"
    click DM4 "https://github.com/headwayio/edi/blob/master/src/transaction.rs"
    click DM5 "https://github.com/headwayio/edi/blob/master/src/generic_segment.rs"
    click Error "https://github.com/headwayio/edi/blob/master/src/edi_parse_error.rs"
    click Serializer "https://github.com/headwayio/edi/blob/master/src/lib.rs"
    click Resources "https://github.com/headwayio/edi/blob/master/resources/schemas.csv"
    click Examples "https://github.com/headwayio/edi/blob/master/examples/parse.rs"
    click Tests "https://github.com/headwayio/edi/tree/master/tests/"

    classDef internal fill:#add8e6,stroke:#000
    classDef external fill:#ffcc99,stroke:#000
    classDef resource fill:#ccffcc,stroke:#000
    classDef error fill:#ff9999,stroke:#000
    classDef serializer fill:#ffe5b4,stroke:#000
```
