# larandvit/ebcdic-parser architecture

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

- Interactive diagram: https://gitdiagram.com/larandvit/ebcdic-parser
- Repository: https://github.com/larandvit/ebcdic-parser

## Overview

This Python application converts EBCDIC records into delimited text using a JSON conversion-rules layout. Users can invoke it through the Python API or command line; the workflow reads the input and rules, interprets records and fields, then writes output and logs. The README documents single- and multi-schema, fixed- and variable-length layouts, anomaly handling, relationship keys, conditional field exclusion, and Python or Java encodings. The sampled implementation is partial and concentrated in `convert.py`, so links between internal processing stages are limited to documented behavior.

Main entry points: [`src/ebcdic_parser/convert.py`](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py) (Conversion run), [`src/ebcdic_parser/__main__.py`](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/__main__.py) (Command line)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Entry points"]
  node_python_api["Python API<br/>[convert.py]"]
  node_cli["Command line<br/>[__main__.py]"]
  node_run["Conversion run<br/>[convert.py]"]
end

subgraph group_rules["Layout interpretation"]
  node_layout_loader["Layout loading<br/>[convert.py]"]
  node_layout_modes["Schema layouts<br/>[convert.py]"]
end

subgraph group_engine["Record conversion"]
  node_record_reader["Record processing<br/>[convert.py]"]
  node_anomaly_handling["Anomaly handling<br/>[convert.py]"]
  node_field_conversion["Field conversion<br/>[convert.py]"]
  node_encoding["Character encoding<br/>[convert.py]"]
  node_record_links["Relationship keys<br/>[convert.py]"]
end

subgraph group_results["Outputs and diagnostics"]
  node_output["Delimited output<br/>[convert.py]"]
  node_logs["Conversion logs<br/>[convert.py]"]
end

node_user(("User"))
node_input_data["EBCDIC file"]
node_rules_file["Rules file"]
node_java["Java encoding"]

node_user -->|"calls"| node_python_api
node_user -->|"runs"| node_cli
node_cli -->|"starts"| node_run
node_python_api -->|"starts"| node_run
node_run -->|"reads"| node_input_data
node_run -->|"loads rules"| node_layout_loader
node_layout_loader -->|"reads"| node_rules_file
node_run -->|"processes records"| node_record_reader
node_layout_loader -->|"defines schemas"| node_layout_modes
node_record_reader -->|"selects layout"| node_layout_modes
node_record_reader -->|"handles skips"| node_anomaly_handling
node_record_reader -->|"converts fields"| node_field_conversion
node_field_conversion -->|"decodes text"| node_encoding
node_encoding -.->|"uses optionally"| node_java
node_record_reader -->|"groups records"| node_record_links
node_run -->|"writes"| node_output
node_run -->|"writes"| node_logs

click node_python_api "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_cli "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/__main__.py"
click node_run "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_layout_loader "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_layout_modes "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_record_reader "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_anomaly_handling "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_field_conversion "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_encoding "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_record_links "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_output "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"
click node_logs "https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python_api,node_cli,node_run,node_user toneBlue
class node_layout_loader,node_layout_modes toneAmber
class node_record_reader,node_anomaly_handling,node_field_conversion,node_encoding,node_record_links toneMint
class node_output,node_logs toneRose
class node_input_data,node_rules_file,node_java toneIndigo
```

## Components

### Entry points

- [Python API](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`
- [Command line](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/__main__.py): `src/ebcdic_parser/__main__.py`
- [Conversion run](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`

### Layout interpretation

- [Layout loading](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`
- [Schema layouts](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`

### Record conversion

- [Record processing](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`
- [Anomaly handling](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`
- [Field conversion](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`
- [Character encoding](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`
- [Relationship keys](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`

### Outputs and diagnostics

- [Delimited output](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`
- [Conversion logs](https://github.com/larandvit/ebcdic-parser/blob/master/src/ebcdic_parser/convert.py): `src/ebcdic_parser/convert.py`

### Other components

- **User**
- **EBCDIC file**
- **Rules file**
- **Java encoding**

## Connections

- User → Python API: calls
- User → Command line: runs
- Command line → Conversion run: starts
- Python API → Conversion run: starts
- Conversion run → EBCDIC file: reads
- Conversion run → Layout loading: loads rules
- Layout loading → Rules file: reads
- Conversion run → Record processing: processes records
- Layout loading → Schema layouts: defines schemas
- Record processing → Schema layouts: selects layout
- Record processing → Anomaly handling: handles skips
- Record processing → Field conversion: converts fields
- Field conversion → Character encoding: decodes text
- Character encoding → Java encoding: uses optionally
- Record processing → Relationship keys: groups records
- Conversion run → Delimited output: writes
- Conversion run → Conversion logs: writes