# consultingmd/ediot architecture

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

- Interactive diagram: https://gitdiagram.com/consultingmd/ediot
- Repository: https://github.com/consultingmd/ediot

## Overview

This repo is a **Ruby gem** (`grnds-ediot`) that **streams an EDI X12 ANSI 834 file** (segment/row-based) and **transforms it into flattened CSV rows** (column-based). It is not a service; it’s a **library** embedded into another Ruby application, plus some **demo Rake tasks** and **test support**.

So the “system” you’re diagramming is primarily a **data transformation pipeline** inside a consumer process:
**File/IO stream → EDI segment parsing → record assembly (834 semantics) → row flattening → CSV output**.

##### Public gem entrypoint / API surface
- `lib/grnds/ediot.rb`
Likely the main require and public module entry.
- `lib/grnds/ediot/version.rb`
Release/versioning.

##### Core transformation pipeline
- `lib/grnds/ediot/parser.rb`
The orchestrator: takes an IO/enumerator (stream), scans, groups segments into records, yields flattened rows.
- `lib/grnds/ediot/segment_parser.rb`
Tokenizes/parses a single EDI segment line (split by `*`, segment name is first element, enforces `:size`).
- `lib/grnds/ediot/record.rb`
Holds one logical “member record” (starts at `INS`), enforces `:occurs`, stores segment instances, produces a flattened row.
- `lib/grnds/ediot/error.rb`
Error types for validation/constraints (too many elements, too many occurrences, etc.).

- `lib/grnds/file_faker.rb` and `lib/grnds/file_faker/*`
Generates faux 834 files and filenames (`faux_834.rb`, `filename.rb`, `walmart_multipart_filename.rb`, ERB templates).
- `spec/**` + `spec/support/**`
RSpec tests and sample fixtures proving parser behavior.
- `Rakefile` (implied demo tasks in README)
- CI/release: `.circleci/*`, `.travis.yml` (legacy), gemspec.

##### What the README tells you to emphasize

- **Streaming-first design**: `Parser.lazy_file_stream(path, line_separator="~" or "\n")` creates a lazy enumerator so large files don’t load into memory.
- **834 “definition” driven**: parsing/flattening is controlled by a `DEFINITION` hash:
- header segment key (first entry) defines record boundaries (e.g., `INS`)
- per-segment constraints: `:size` (max elements), `:occurs` (max repeats per record)
- **Record boundary detection**: file is “unbounded”; you know a record ends when the next header segment begins.
- **Output contract**: `parser.row_keys` gives CSV header keys; `parser.parse(enum) { |row| ... }` yields row arrays aligned to those keys.

##### `Parser` → Consumer block → `CSV::Row` → Output CSV file

To show:
- Record boundary logic: **Parser detects new record on header segment key (e.g., INS)** and “flushes” prior record.
- Error path: SegmentParser/Record → Error → Consumer (exception)

- `Grnds::Ediot::Parser`
- depends on: `SegmentParser`, `Record`, `Error`
- exposes: `row_keys`, `parse`, `.lazy_file_stream`
- owns: current_record state, definition
- `Grnds::Ediot::SegmentParser`
- exposes: parse(line) → structured segment
- validates: `:size` constraint
- `Grnds::Ediot::Record`
- stores: segments by type + occurrence index
- validates: `:occurs`
- outputs: flattened row
- `Grnds::Ediot::Error`
- defines parse/validation exceptions

Optionally include:

##### Relationships & interactions to explicitly encode (don’t leave implicit)

- **Input delimiter**: default `~` (explicitly called out in README) with option to override (`"\n"`).
- **Segment structure**: `SEGMENT*elem1*elem2...` and constraints from DEFINITION.
- **Record semantics**:
- Header key begins record (`INS` in default definition).
- Record end inferred by next header.

##### Architectural patterns / principles to highlight

- **Streaming / iterator-based ETL**: avoids loading whole file.
- **Definition-driven parsing**: parsing behavior is configured by a hash (easy testing + extensibility).
- **Separation of concerns**:
- Parser = orchestration + record boundary detection
- SegmentParser = syntactic parsing + size validation
- Record = semantic aggregation + occurs validation + flattening
- **Fail-fast validation**: errors thrown when constraints exceeded.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Level 1: System Context
%% =========================
subgraph "System Context (Library embedded in a Ruby process)"
direction TB

EDI["EDI 834 File<br/>(segment-delimited, default ~)"]:::file
APP["Consumer Ruby App / ETL Job<br/>(controls IO + CSV writing)"]:::external
GEM["grnds-ediot Gem<br/>(EDI 834 -> flattened CSV rows)"]:::gem
CSV["Output CSV File<br/>(header + rows)"]:::file

EDI -->|"streamed IO (no full file load)"| APP
APP -->|"API calls: Parser.new / .lazy_file_stream / #parse"| GEM
GEM -->|"yield rows to block"| APP
APP -->|"writes CSV header+rows"| CSV
end

%% Optional ecosystem
subgraph "Release & CI (optional ecosystem)"
direction TB
GIT["Git Tag / Release Commit"]:::external
CI["CircleCI Pipeline"]:::ci
RUBY["RubyGems.org<br/>(gem distribution)"]:::external

GIT -->|"trigger build/release"| CI
CI -->|"publish gem"| RUBY
end

%% =========================
%% Level 2: Runtime / Pipeline
%% =========================
subgraph "Runtime View (inside consumer process)"
direction TB

subgraph "External / Consumer Code"
direction TB
CSVW["Consumer CSV Writer<br/>(CSV::Row / File output)"]:::external
end

subgraph "grnds-ediot (core pipeline)"
direction TB

ENTRY["lib/grnds/ediot.rb<br/>Public entrypoint"]:::gem
VER["lib/grnds/ediot/version.rb<br/>Versioning"]:::gem

DEF["834 DEFINITION (Hash)<br/>header key + :size + :occurs<br/>(drives schema + validation)"]:::config

ENUM["File Stream Enumerator<br/>Parser.lazy_file_stream(path, sep=~ or LF)"]:::runtime
PARSER["Grnds::Ediot::Parser<br/>Orchestrates stream -> segments -> records -> rows"]:::core
SEG["Grnds::Ediot::SegmentParser<br/>Parse SEG*e1*e2.. + validate :size"]:::core
REC["Grnds::Ediot::Record<br/>Aggregate per INS record + validate :occurs + flatten row"]:::core
ERR["Grnds::Ediot::Error<br/>Fail-fast constraint exceptions"]:::error

ENTRY -->|"requires / exposes API"| PARSER
ENTRY -->|"requires"| SEG
ENTRY -->|"requires"| REC
ENTRY -->|"requires"| ERR
VER -->|"version constant"| ENTRY

DEF -->|"configures parsing + schema"| PARSER
DEF -->|"constraints (:size)"| SEG
DEF -->|"constraints (:occurs)"| REC

ENUM -->|"segment_line (String, delimited)"| PARSER
PARSER -->|"parse(line) -> ParsedSegment(name,elements[])"| SEG
SEG -->|"ParsedSegment(name,elements[])"| PARSER

PARSER -->|"record boundary detect:<br/>header segment (e.g., INS)<br/>flush prior record"| REC
PARSER -->|"append segment / validate occurs"| REC
REC -->|"emit row (Array aligned to row_keys)"| PARSER
PARSER -->|"yield row to consumer block"| CSVW

SEG -->|"raise validation error (:size exceeded)"| ERR
REC -->|"raise validation error (:occurs exceeded)"| ERR
PARSER -->|"bubble exceptions"| ERR
ERR -->|"exception propagated to consumer"| APP

PARSER -->|"row_keys (derived from DEFINITION<br/>+ occurs/size expansion)"| CSVW
end

%% Data file to enumerator and writer to output
EDI -->|"read + split by separator"| ENUM
CSVW -->|"write to file"| CSV
end

%% =========================
%% Level 3: Repo Ecosystem (tests + utilities)
%% =========================
subgraph "Test & Demo Utilities (non-core)"
direction TB

subgraph "FileFaker (demo/faux EDI generator)"
direction TB
FFENTRY["Grnds::FileFaker<br/>Entry"]:::test
FFDIR["lib/grnds/file_faker/<br/>(templates + helpers)"]:::test
FAUX["Faux 834 Generator<br/>(build faux EDI content)"]:::test
FNAME["Filename Helpers"]:::test
WM["Walmart Multipart Filename Helper"]:::test
ERBH["header.erb"]:::test
ERBM["meta.erb"]:::test
ERBR["record.erb"]:::test

FFENTRY -->|"uses"| FFDIR
FFDIR -->|"implements"| FAUX
FFDIR -->|"implements"| FNAME
FNAME -->|"variant"| WM
FFDIR -->|"renders ERB"| ERBH
FFDIR -->|"renders ERB"| ERBM
FFDIR -->|"renders ERB"| ERBR
end

subgraph "RSpec Test Suite"
direction TB
SPECDIR["spec/grnds/ediot/<br/>(core behavior verification)"]:::test
PSPEC["parser_spec.rb"]:::test
RSPEC["record_spec.rb"]:::test
SSPEC["segment_parser_spec.rb"]:::test
ISPEC["spec/grnds/ediot_spec.rb<br/>(gem-level integration)"]:::test
SHELP["spec/spec_helper.rb<br/>(test configuration)"]:::test
SUPPORT["spec/support/<br/>(fixtures: sample inputs/outputs)"]:::test

SHELP -->|"loads support"| SUPPORT
SPECDIR -->|"contains"| PSPEC
SPECDIR -->|"contains"| RSPEC
SPECDIR -->|"contains"| SSPEC
ISPEC -->|"covers integration"| PARSER
PSPEC -->|"tests"| PARSER
RSPEC -->|"tests"| REC
SSPEC -->|"tests"| SEG
SUPPORT -->|"feeds fixtures to tests"| PSPEC
end

subgraph "Build / Packaging / CI Config"
direction TB
RAKE["Rakefile<br/>(demo/build tasks)"]:::ci
CICONF[".circleci/config.yml"]:::ci
PUBLISH[".circleci/publish.sh<br/>(release publishing)"]:::ci
TRAVIS[".travis.yml<br/>(legacy)"]:::ci
GEMSPEC["grnds-ediot.gemspec<br/>(packaging)"]:::ci

RAKE -->|"invokes demo tasks"| FFENTRY
CICONF -->|"runs tests/build"| SPECDIR
CICONF -->|"calls"| PUBLISH
end
end

%% =========================
%% Click Events (component_mapping)
%% =========================
click ENTRY "https://github.com/consultingmd/ediot/blob/master/lib/grnds/ediot.rb"
click VER "https://github.com/consultingmd/ediot/blob/master/lib/grnds/ediot/version.rb"
click PARSER "https://github.com/consultingmd/ediot/blob/master/lib/grnds/ediot/parser.rb"
click SEG "https://github.com/consultingmd/ediot/blob/master/lib/grnds/ediot/segment_parser.rb"
click REC "https://github.com/consultingmd/ediot/blob/master/lib/grnds/ediot/record.rb"
click ERR "https://github.com/consultingmd/ediot/blob/master/lib/grnds/ediot/error.rb"

click FFENTRY "https://github.com/consultingmd/ediot/blob/master/lib/grnds/file_faker.rb"
click FFDIR "https://github.com/consultingmd/ediot/tree/master/lib/grnds/file_faker/"
click FAUX "https://github.com/consultingmd/ediot/blob/master/lib/grnds/file_faker/faux_834.rb"
click FNAME "https://github.com/consultingmd/ediot/blob/master/lib/grnds/file_faker/filename.rb"
click WM "https://github.com/consultingmd/ediot/blob/master/lib/grnds/file_faker/walmart_multipart_filename.rb"
click ERBH "https://github.com/consultingmd/ediot/blob/master/lib/grnds/file_faker/header.erb"
click ERBM "https://github.com/consultingmd/ediot/blob/master/lib/grnds/file_faker/meta.erb"
click ERBR "https://github.com/consultingmd/ediot/blob/master/lib/grnds/file_faker/record.erb"

click SPECDIR "https://github.com/consultingmd/ediot/tree/master/spec/grnds/ediot/"
click PSPEC "https://github.com/consultingmd/ediot/blob/master/spec/grnds/ediot/parser_spec.rb"
click RSPEC "https://github.com/consultingmd/ediot/blob/master/spec/grnds/ediot/record_spec.rb"
click SSPEC "https://github.com/consultingmd/ediot/blob/master/spec/grnds/ediot/segment_parser_spec.rb"
click ISPEC "https://github.com/consultingmd/ediot/blob/master/spec/grnds/ediot_spec.rb"
click SHELP "https://github.com/consultingmd/ediot/blob/master/spec/spec_helper.rb"
click SUPPORT "https://github.com/consultingmd/ediot/tree/master/spec/support/"

click RAKE "https://github.com/consultingmd/ediot/tree/master/Rakefile"
click CICONF "https://github.com/consultingmd/ediot/blob/master/.circleci/config.yml"
click PUBLISH "https://github.com/consultingmd/ediot/blob/master/.circleci/publish.sh"
click TRAVIS "https://github.com/consultingmd/ediot/blob/master/.travis.yml"
click GEMSPEC "https://github.com/consultingmd/ediot/blob/master/grnds-ediot.gemspec"

%% =========================
%% Styles
%% =========================
classDef gem fill:#1f4b99,stroke:#0e2a5a,color:#ffffff,stroke-width:1.5px
classDef core fill:#2b6cb0,stroke:#123b6d,color:#ffffff,stroke-width:1.5px
classDef runtime fill:#2f855a,stroke:#1f5c3d,color:#ffffff,stroke-width:1.5px
classDef config fill:#6b46c1,stroke:#3c2072,color:#ffffff,stroke-width:1.5px
classDef error fill:#c53030,stroke:#7a1c1c,color:#ffffff,stroke-width:1.5px
classDef external fill:#4a5568,stroke:#2d3748,color:#ffffff,stroke-width:1.5px
classDef file fill:#2d3748,stroke:#1a202c,color:#ffffff,stroke-width:1.5px
classDef test fill:#718096,stroke:#4a5568,color:#ffffff,stroke-width:1.5px,stroke-dasharray: 5 4
classDef ci fill:#b7791f,stroke:#6b3f0b,color:#ffffff,stroke-width:1.5px
```
