hello-ediflow

Posted on May 14

Building EDIFlow - Lessons Learned: What Worked, What Didn't, What's Next (Part 6)

#typescript #cleanarchitecture #opensource #edi

Series: Building EDIFlow - A Clean Architecture Journey in TypeScript (Part 6/6 — Final)
Reading Time: ~10 minutes

The Journey So Far

Over five articles, we built an entire EDI parsing library layer by layer:

Part	Layer	Key Insight
Part 1	Why?	Honest motivation — learning by building
Part 2	Domain	Entities, Value Objects, business rules
Part 3	Application	Use Cases, Ports, DTOs, Factories
Part 4	Infrastructure	Parsers, Repositories, Data Packages
Part 5	Presentation	CLI, DI Container, Wiring
Part 6	Lessons	What worked, what didn't

Now it's time for honesty. Not "Clean Architecture is amazing" — but what actually happened when one person built a real library with it.

The Numbers (May 2026)

Metric	Value
Packages on NPM	13
Tests	711 passing
Code Coverage	≥ 90% (core)
EDIFACT message types	728 (D.96A: 126, D.01B: 211, D.12A: 196, D.20B: 195)
X12 transaction sets	612 (004010: 293, 006040: 319)
HIPAA transaction sets	14
EANCOM messages	49
Total message definitions	1.403
NPM downloads (since Jan 2026)	7.500+
TypeScript errors	0
Time to build	~4 months (solo)

What Worked — And Why I'd Do It Again

✅ Clean Architecture made multi-standard possible

This is the single biggest win. When I started in January 2026 with EDIFACT, I defined IMessageParser, IMessageBuilder, IValidationService in the Application Layer. Three months later, when I added X12 support, zero code changed in the Domain or Application layers. The X12 parser just implemented the same interfaces.

HIPAA? Same interfaces. EANCOM? Same interfaces. The architecture literally paid for itself.

✅ TypeScript strict mode caught real bugs

strict: true in tsconfig.json was non-negotiable from day one. It caught:

Missing null checks on optional segment elements
Wrong discriminated union narrowing in DTOs
Type mismatches between EDIFACT and X12 parser outputs

Estimated bugs prevented: dozens. Worth every extra type annotation.

✅ Test-Driven Development — but not dogmatically

I wrote tests first for domain entities, value objects, and use cases. But for parsers? I wrote the parser first, then added tests — because EDIFACT tokenization logic is discovery work. You don't know the edge cases until you try real messages.

Rule of thumb that worked: TDD for known interfaces (Use Cases, Services). Tests-after for discovery work (Parsers, Tokenizers).

711 tests give me confidence to refactor aggressively.

✅ Data packages as separate npm packages

Each EDIFACT version, each X12 version is its own npm package. Benefits:

Users install only what they need
Bundle sizes stay small (a D.96A user doesn't download D.20B)
Independent versioning — fix a typo in D.96A without releasing all packages
13 packages sounds like a lot, but npm workspaces + tsup make publishing painless

✅ Monorepo with npm workspaces

One repository, 13 packages, shared tooling:

One vitest.workspace.ts for all tests
One tsup config pattern
Cross-package imports via package names (import { X } from '@ediflow/core')
npm run build and npm test at root level — CI is simple

✅ Business Object Mapping — the killer feature

This is what no other Node.js EDI library does. Instead of navigating message.segments[3].elements[1].components[0], you get:

const order = mappingService.map(message, structure, 'name');
// order["Beginning of message"]["Document identifier"] === "ORDER-001"

Round-trip: map() converts EDI → JSON, unmap() converts JSON → EDI. Same structure definition drives both directions. This feature alone justifies the entire project.

What Didn't Work — Honest Mistakes

⚠️ I over-engineered the validation architecture early on

The first version had IValidationRule, IValidationService, ComposableValidationService, ValidationResult, ValidationError, StructuralValidationService, StructuralValidationContext... all before I had a second standard to validate.

Lesson: Build the simplest validation first. Extract abstractions when you actually need them (when adding X12). Some of this complexity would have emerged naturally instead of being designed upfront.

⚠️ Data package JSON format evolved 3 times

Version 1: flat JSON with segment references. Version 2: nested with composites. Version 3: with syntax rules and code lists. Each migration touched all 8+ data packages.

Lesson: Prototype the data format with 2-3 message types before generating 195. Schema changes to hundreds of files are painful.

⚠️ README took too long to get right

The first README was a technical spec. Nobody understood what the project does. I rewrote it 4 times before landing on: problem → solution → code example → install.

Lesson: Write the README before writing code. If you can't explain it simply, you don't understand the problem well enough.

⚠️ CLI shipped too early, too buggy

I wanted to publish fast — so the CLI went out with v0.1.0 before it was properly tested end-to-end. The commands looked right on paper, but in practice: wrong output formats, missing edge cases, flags that didn't work as documented.

It wasn't until v0.3.0 — when I wrote real examples for every standard (EDIFACT, X12, HIPAA, EANCOM) and actually ran them — that the CLI became reliable. Generating examples forced me to use the CLI the way a real user would. Every bug surfaced immediately.

Lesson: Unit tests prove your code works in isolation. But nothing replaces running real EDI files through the full pipeline end-to-end. Write examples first — they're the best integration tests you'll ever have.

What I'd Change If Starting Over

1. Start with 2 standards from day one

I built EDIFACT first, then added X12. The interfaces were mostly right — but "mostly right" means small refactors in 50+ files when adding the second standard. If I'd built EDIFACT and X12 in parallel from the start, the abstractions would have been better immediately.

2. Schema-first data package design

Define the JSON schema for message definitions first, validate it, then generate data. I did it backwards: generate data, then realize the schema isn't quite right, refactor.

3. Fewer abstraction layers in core

Some classes in @ediflow/core exist for architectural purity rather than practical need. EDIMessageFactory.create() is a wrapper around a constructor. EDIMessageValidationService is a thin wrapper around ComposableValidationService. If it adds indirection without value, remove it.

The Architecture in One Diagram

┌─────────────────────────────────────────┐
│  CLI (commander.js)                     │  Presentation
│  ┌───────────────────────────────────┐  │
│  │  DI Container                     │  │  Wiring
│  │  ┌─────────────────────────────┐  │  │
│  │  │  EDIFACT Parser · X12 Parser│  │  │  Infrastructure
│  │  │  File Repository · Builders │  │  │
│  │  │  ┌───────────────────────┐  │  │  │
│  │  │  │  Use Cases · Services │  │  │  │  Application
│  │  │  │  Ports · DTOs · Factory│ │  │  │
│  │  │  │  ┌─────────────────┐  │  │  │  │
│  │  │  │  │ EDIMessage      │  │  │  │  │  Domain
│  │  │  │  │ Segment · Element│ │  │  │  │
│  │  │  │  │ Standard · Delim│  │  │  │  │
│  │  │  │  └─────────────────┘  │  │  │  │
│  │  │  └───────────────────────┘  │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Dependencies point inward. Always. No exceptions.

What's Next for EDIFlow

Feature	Timeline	Status
Platform / Web UI	Q4 2026	Planned
REST API	Q3 2026	Planned
IDOC / SAP	2027	Vision
VDA (automotive)	2027	Vision
More HIPAA sets	Q3 2026	Planned

The architecture makes all of this possible. Adding a REST API? Another Presentation Layer → same Use Cases → same Infrastructure. Adding IDOC? Another Infrastructure implementation → same Application Layer interfaces.

That's the promise of Clean Architecture. And after 4 months and 711 tests, I can say: it delivers.

Thank You

If you've read all 6 parts — thank you. Writing this series forced me to think clearly about every decision. I hope it helps you build better TypeScript applications, whether that's an EDI library or something completely different.

The core principles are universal: