VanillaEDI

Deployed October 2026

Architectural Overview

Case Study: Building VanillaEDI — From Engineering Challenge to Open-Source Utility

Overview

Electronic Data Interchange (EDI) standards like ANSI X12 have powered enterprise supply chains for decades. Despite being decades old, these rigid, text-delimited formats still govern how retail giants, suppliers, and logistics providers communicate.

VanillaEDI was built as a modern developer experiment: Can we take a legacy, notoriously painful protocol and turn it into a clean, modern, developer-friendly REST API?

The result is a lightweight, stateless open-source microservice built on FastAPI and Pydantic v2 that converts complex EDI files into structured JSON—and generates outbound EDI files from simple HTTP requests.

The Challenge: Making Legacy EDI Developer-Friendly

Working with standard X12 EDI often presents several pain points for modern developers:

  • Obscure File Formats: Text strings packed with asterisks, tildes, and positional segments (e.g., BEG*00*SA*PO-998231**20260928~) make debugging and manual parsing tedious.
  • Brittle Parsing Rules: Non-standard element separators, missing header segments, and unexpected line breaks break simple regex parsers.
  • Heavy Tooling: Most existing solutions are either expensive enterprise middleware platforms or heavy, file-based translation engines designed for legacy desktop servers.
  • Lack of Modern API Design: Most traditional tools lack native OpenAPI documentation, dynamic JSON schema validation, or async HTTP webhook hooks.

The Approach: A Stateless, High-Coverage Microservice

VanillaEDI treats EDI parsing like any standard REST endpoint. Built with Python 3.14+, FastAPI, and Pydantic v2, it prioritizes speed, type safety, and ease of deployment.

Key Architectural Decisions

  • Zero-Storage Stateless Design: Incoming files are parsed entirely in memory. No databases, no local storage queues, and no cron jobs required.
  • Strict Schema Enforcement: Every document type utilizes dedicated Pydantic schemas, ensuring structured JSON output, auto-generated Swagger documentation, and clear error messaging.
  • Resilient Delimiter Fallbacks: Parser units dynamically detect custom element separators and segment terminators, gracefully handling non-standard formatting.
  • Async Webhook Dispatcher: Users can upload an EDI file and supply a webhook_url parameter; VanillaEDI parses the file and forwards the JSON payload asynchronously in the background.
  • Outbound Generator: Hitting a generator endpoint allows developers to pass simple JSON payloads and receive fully compliant ANSI X12 text in response.

Supported Document Types

Document Type ANSI X12 Code Direction Purpose
Purchase Order 850 Inbound / Outbound Parses purchase order header details, shipping addresses, and line items.
Invoice 810 Inbound / Outbound Converts billing line items to JSON or generates raw outbound X12 invoice files.
Ship Notice / Manifest 856 Inbound / Outbound Handles hierarchical packing and shipment data.
Functional Ack 997 Outbound Instantly generates 997 response files to acknowledge document receipt.

Technical Standards & Results

  • 100% Test Coverage: Maintained 100% branch test coverage using pytest across all parsers, generators, utilities, and API endpoints.
  • Automated CI/CD: Integrated GitHub Actions workflows enforce strict coverage gates on every pull request.
  • Docker Ready: Packaged into a minimal Docker container, making it easy to run locally or deploy to serverless platforms like AWS ECS or Google Cloud Run.
  • Open Source: Released under the MIT License with complete developer documentation, security reporting guidelines, and contributing workflows.

Tech Stack

  • Language: Python 3.14+
  • Framework: FastAPI, Pydantic v2, Uvicorn
  • Testing: Pytest, Pytest-Cov, HTTPX
  • DevOps: Docker, GitHub Actions