# moov-io/irs architecture

> Architecture diagram of the GitHub repository moov-io/irs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moov-io/irs
- Repository: https://github.com/moov-io/irs

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entrypoints
    subgraph "Entrypoints" 
        CLI_main["CLI: cmd/irs/main.go"]:::entry
        CLI_test["CLI Test: cmd/irs/cmd_test.go"]:::entry
        HTTP_server["HTTP Server: pkg/service/server.go"]:::entry
        HTTP_handlers["HTTP Handlers: pkg/service/handlers.go"]:::entry
        OpenAPI_spec["OpenAPI Spec: api/api.yml"]:::spec
    end

    %% Core Library
    subgraph "Core Library"
        Parser["Parser Module"]:::core
        Errors["Error Utils: pkg/utils/errors.go"]:::core
        Validation["Validation Service"]:::core
        PDF_code["PDF Generator: pkg/pdf_generator/Pdf1099Misc.go"]:::core
        PD_script["pdftk Script: scripts/install_pdftk.sh"]:::external
        Encryption["Encryption Service: pkg/encrypter/encrypter.go"]:::core
        Storage["Document Storage: pkg/documents/model_document.go"]:::core
        Configuration["Configuration: pkg/config/specification.go"]:::core
        ClientSDK["Client SDK: pkg/client/client.go"]:::spec
        Migration["Migration: migrations/001_documents.up.sql"]:::external
    end

    %% External Systems
    subgraph "External Systems"
        FS["File System"]:::external
        PD["pdftk Binary"]:::external
        SQLDB["SQL Database"]:::external
        Dockerfile["Dockerfile"]:::external
        DockerCompose["docker-compose.yml"]:::external
        Makefile["Makefile"]:::external
        CI_CD["CI/CD Workflows"]:::external
    end

    %% Data Flows
    CLI_main -->|uses config| Configuration
    CLI_test -->|tests| Configuration
    HTTP_server -->|loads spec| OpenAPI_spec
    HTTP_handlers -->|handles routes| Parser
    HTTP_handlers -->|handles routes| Validation
    HTTP_handlers -->|handles routes| PDF_code
    HTTP_handlers -->|handles routes| Storage
    HTTP_handlers -->|uses client SDK| ClientSDK
    Configuration -->|settings| Parser
    Configuration -->|settings| Validation
    Parser -->|ASCII/JSON| Errors
    Parser -->|build models| Validation
    Validation -->|validates models| PDF_code
    PDF_code -->|FDF| PD_script
    PD_script -->|executes| PD
    Validation -->|errors->| HTTP_handlers
    Validation -->|records| Storage
    Storage -->|SQL statements| SQLDB
    Parser -->|read/write| FS
    ClientSDK -->|generated from| OpenAPI_spec
    OpenAPI_spec -->|drives| HTTP_handlers
    OpenAPI_spec -->|drives| ClientSDK
    Dockerfile -->|containerizes| HTTP_server
    DockerCompose -->|orchestrates| HTTP_server
    DockerCompose -->|orchestrates| SQLDB
    CI_CD -->|build/test| CLI_main

    %% Click Events
    click CLI_main "https://github.com/moov-io/irs/blob/master/cmd/irs/main.go"
    click CLI_test "https://github.com/moov-io/irs/blob/master/cmd/irs/cmd_test.go"
    click HTTP_server "https://github.com/moov-io/irs/blob/master/pkg/service/server.go"
    click HTTP_handlers "https://github.com/moov-io/irs/blob/master/pkg/service/handlers.go"
    click OpenAPI_spec "https://github.com/moov-io/irs/blob/master/api/api.yml"
    click Parser "https://github.com/moov-io/irs/blob/master/pkg/file/file.go"
    click Parser "https://github.com/moov-io/irs/blob/master/pkg/file/file_instance.go"
    click Parser "https://github.com/moov-io/irs/blob/master/pkg/file/constants.go"
    click Parser "https://github.com/moov-io/irs/blob/master/pkg/records/record.go"
    click Parser "https://github.com/moov-io/irs/blob/master/pkg/subrecords/subrecord.go"
    click Errors "https://github.com/moov-io/irs/blob/master/pkg/utils/errors.go"
    click PDF_code "https://github.com/moov-io/irs/blob/master/pkg/pdf_generator/Pdf1099Misc.go"
    click PD_script "https://github.com/moov-io/irs/blob/master/scripts/install_pdftk.sh"
    click Encryption "https://github.com/moov-io/irs/blob/master/pkg/encrypter/encrypter.go"
    click Storage "https://github.com/moov-io/irs/blob/master/pkg/documents/model_document.go"
    click Configuration "https://github.com/moov-io/irs/blob/master/pkg/config/specification.go"
    click ClientSDK "https://github.com/moov-io/irs/blob/master/pkg/client/client.go"
    click Migration "https://github.com/moov-io/irs/blob/master/migrations/001_documents.up.sql"
    click Dockerfile "https://github.com/moov-io/irs/tree/master/Dockerfile"
    click DockerCompose "https://github.com/moov-io/irs/blob/master/docker-compose.yml"
    click Makefile "https://github.com/moov-io/irs/tree/master/Makefile"
    click CI_CD "https://github.com/moov-io/irs/blob/master/.github/workflows/go.yml"

    %% Styles
    classDef entry fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef external fill:#FFEFD5,stroke:#D2691E,color:#D2691E;
    classDef spec fill:#F3F4F6,stroke:#6E6E6E,color:#6E6E6E;
```
