# trailblazer/reform architecture

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

- Interactive diagram: https://gitdiagram.com/trailblazer/reform
- Repository: https://github.com/trailblazer/reform

## Overview

##### Main Components Identification
- Library Core: This is the “lib/reform.rb” file that ties the library together.
- Form Component: Represented by the “Reform::Form” class in “lib/reform/form.rb” and its related submodules (call, coercion, composition, dry, module, populator, prepopulate, validate).
- Contract & Validation: The “Reform::Contract” components (and its files in lib/reform/contract), as well as “lib/reform/validation” which covers error groups and custom validations. Also highlight error management with “lib/reform/errors.rb”.
- Result Handling: Managed by “lib/reform/result.rb”.
- Versioning/Metadata: “lib/reform/version.rb” and gemspec files provide metadata that allows the gem to be integrated into other projects.
- Testing & CI: The “test” directory contains numerous tests to validate different facets (coercion, contract, validation, nested forms etc.), while the “.github” directory provides CI configurations (including workflows for multiple Ruby engines).

##### Relationships and Interactions between Components
- The Form component acts as the primary interface for users: when a user instantiates a form, it wraps around one or more models. The form then uses validations (via either ActiveModel or dry-validation based on configuration) to validate incoming parameters.
- The Contract subcomponent is responsible for ensuring that the input meets certain expectations, whereas the Validation component groups and manages errors.
- The Form’s “validate”, “sync”, and “save” methods illustrate the data flow: input parameters → update form values → validate → (optionally) sync back to the model.
- The design also supports nested objects (with nested forms and collections), so you’d want to show the recursion between a parent form and its nested forms.
- The CI pipelines, running through various configurations in .github/workflows, ensure that the gem is tested across different execution environments.

##### Architectural Patterns and Design Principles
- Separation of concerns is evident: models remain unchanged during form validation, and the logic for validation, coercion, and composition is encapsulated in dedicated modules.
- The composite pattern is utilized for nested and composed forms, where multiple models can be integrated into a single form.
- The API is designed for immutability during validation, then explicit syncing of state to models upon saving.
- Framework-agnostic design allows it to integrate with Rails (via reform-rails) or be used standalone.

##### Relevant Technologies, Frameworks, or Libraries
- Ruby and the RubyGems packaging system.
- ActiveModel (for validations in older or specific Rails integrations) and dry-validation (the recommended backend).
- Testing frameworks for Ruby (likely Minitest) as indicated by the “test” directory.
- CI/CD tools configured via GitHub Actions workflows (RC CI, jruby, legacy, truffleruby).

##### Detail and Clarity
- That every module is shown, including the separation of responsibilities (input processing, validation, syncing).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        LibraryCore["Library Core"]
    end

    %% Form Handling Layer
    subgraph "Form Handling"
        Form["Reform::Form (API)"]
        SubFormModules["Form Modules (submodules)"]
        Nested["Nested Forms"]
    end

    %% Contract & Validation Layer
    subgraph "Contract & Validation"
        ContractFile["Reform::Contract (file)"]
        ContractDir["Contract Submodules"]
        ValidationFile["Validation Component (file)"]
        ValidationDir["Validation Submodules"]
        Errors["Error Management"]
    end

    %% Result Handling & Versioning
    subgraph "Result and Versioning"
        Result["Result Handling"]
        Version["Version"]
        Gemspec["Gemspec"]
    end

    %% Testing & CI Layer
    subgraph "Testing & CI"
        Tests["Testing"]
        CI["CI Workflows"]
    end

    %% Relationships
    LibraryCore -->|"ties"| Form
    Form -->|"invokes"| ContractFile
    ContractFile -->|"extends"| ContractDir
    ContractFile -->|"validates_with"| ValidationFile
    ValidationFile -->|"organizes"| ValidationDir
    ValidationFile -->|"groups_errors"| Errors
    Form -->|"contains"| Nested
    Form -->|"syncs_to"| Result
    LibraryCore -->|"provides"| Version
    LibraryCore -->|"integrates"| Gemspec
    Tests -->|"covers"| LibraryCore
    CI -->|"executes_for"| LibraryCore

    %% Styles
    classDef core fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef form fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef contract fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef result fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef meta fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef test fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px;

    class LibraryCore core;
    class Form,SubFormModules,Nested form;
    class ContractFile,ContractDir,ValidationFile,ValidationDir,Errors contract;
    class Result core;
    class Version,Gemspec meta;
    class Tests,CI test;

    %% Click Events
    click LibraryCore "https://github.com/trailblazer/reform/blob/master/lib/reform.rb"
    click Form "https://github.com/trailblazer/reform/blob/master/lib/reform/form.rb"
    click SubFormModules "https://github.com/trailblazer/reform/tree/master/lib/reform/form"
    click ContractFile "https://github.com/trailblazer/reform/blob/master/lib/reform/contract.rb"
    click ContractDir "https://github.com/trailblazer/reform/tree/master/lib/reform/contract"
    click ValidationFile "https://github.com/trailblazer/reform/blob/master/lib/reform/validation.rb"
    click ValidationDir "https://github.com/trailblazer/reform/tree/master/lib/reform/validation"
    click Errors "https://github.com/trailblazer/reform/blob/master/lib/reform/errors.rb"
    click Result "https://github.com/trailblazer/reform/blob/master/lib/reform/result.rb"
    click Version "https://github.com/trailblazer/reform/blob/master/lib/reform/version.rb"
    click Gemspec "https://github.com/trailblazer/reform/blob/master/reform.gemspec"
    click Tests "https://github.com/trailblazer/reform/tree/master/test"
    click CI "https://github.com/trailblazer/reform/tree/master/.github/workflows"
```
