How moov-io/irs works
Project Type and Purpose
• This is an open-source Go library and CLI/Web tool for reading, writing, converting, validating, and printing IRS FIRE (Filing Information Returns Electronically) files. It operates over multiple representations (ASCII FIRE, JSON, PDF, SQL) and exposes both command-line subcommands and an HTTP API.
File Structure Analysis
• Top-level:
• cmd/irs – CLI entrypoint with subcommands (convert, print, validator, web).
• pkg/… – Core library modules (parsing records, services, file I/O, PDF generator, encryption, client SDK).
• api/ & .openapi-generator – OpenAPI spec + generator config for client SDK.
• migrations/ – SQL schema definitions for persistent document storage.
• configs/ & docs/ – Default configuration, user guides, running instructions.
• Dockerfile, docker-compose.yml, Makefile – Containerization and build/deploy.
• test/ & fuzz-reader – Fuzz tests and unit tests for robustness.
Key Components
a. CLI Layer (cmd/irs)
• Subcommands invoke library services.
b. HTTP Server (pkg/service + cmd/irs web)
• REST endpoints: /convert, /print, /validator, /health.
• Uses OpenAPI spec (api/api.yml) to define routes.
c. Core Modules (pkg/…)
1. File I/O & Parser (pkg/file, pkg/records, pkg/subrecords) – Reads/writes ASCII and JSON, builds in-memory record models.
2. Validation (pkg/utils/errors, pkg/service/handlers) – Business rules enforcement.
3. PDF Generator (pkg/pdf_generator + pdftk) – FDF templates + PDF fill.
4. Encryption (pkg/encrypter) – Optional data encryption service.
5. Document Storage (pkg/documents, migrations) – Persists JSON/ASCII to a SQL database.
6. Configuration (pkg/config, configs/config.default.yml) – Environment & behavior settings.
7. Client SDK (pkg/client generated via OpenAPI) – External consumer library.
d. External Dependencies
• File system (reading/writing input/output files)
• pdftk (Shell script install_pdftk.sh)
• SQL database (migrations apply schema)
• Docker (container runtime)
• CI/CD (GitHub Actions workflows, CodeQL)
Relationships & Data Flows
• CLI/Web → Configuration → Core Services
• Core Services → File I/O / Parser → In-Memory Models
• Models → Validator → (errors → CLI/Web)
• Models → PDF Generator → pdftk → PDF output
• Models → Document Storage → SQL DB
• CLI/Web → pkg/client (if acting as client) → HTTP API
• External Program pdftk invoked by PDF generator
• OpenAPI spec drives both server handlers and SDK generation
Architectural Patterns & Principles
• Layered architecture (Presentation → Service → Domain → Persistence)
• Separation of concerns: parsing, validation, generation, storage, config
• OpenAPI-first for HTTP API design and client SDK generation
• Modular Go packages for testability and reusability
• Fuzz testing for parser robustness
Essential Elements
• Component labels (e.g., “Parser Module”, “Validation Service”)
• Callouts for configuration files and CI/CD workflows