# ismasan/plumb architecture

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

- Interactive diagram: https://gitdiagram.com/ismasan/plumb
- Repository: https://github.com/ismasan/plumb

## Overview

##### Main “layers” or components
- Composite Types and Advanced APIs – Illustrate the specialized type categories such as Types::Hash, Types::Array, Types::Tuple, Types::Stream, and Types::Data (data structures/immutable structs). Each of these is responsible for validating and transforming nested data.
- Policies & Helpers – Show there’s a layer that encapsulates custom policies (e.g., default values, options, “present”, “not”) that allow further behavior composition (like rescue or transform behavior).
- Visitors / JSON Schema Generation – Create an element for the JSON schema visitor (Plumb::JSONSchemaVisitor) which compiles the defined types into JSON Schema formats.
- Benchmarks, Examples, Specs – Although not part of the runtime architecture, note the supporting directories (bench, examples, spec) are used for performance testing, documentation through real use cases, and validation via tests.

##### Relationships and data flow
- An element for “Type Composition” where various components (core types, adapters, custom steps) merge to create the end-to-end validation/coercion routines.
- Finally, branch off a side component that converts the internal definitions into JSON Schema through the visitor. This represents the introspection/documentation aspect of the library.

##### Important architectural patterns and design principles
- Pipeline pattern: Emphasizes sequential, step-by-step processing where steps can be wrapped by middleware (using “around”) to provide logging, metrics, or error handling.
- Separation of concerns: Different modules handle validation, transformation, and building of custom data structures (Types::Data) while still interoperating.

##### Relevant technologies, libraries, and integration points
- Ruby is the primary language.
- Also mention integration with other libraries (e.g., Concurrent Ruby usage in concurrent array processing).

- Visually separate the concerns: one section for basic type handling and composability, another for pipeline processing and middleware, and separate out the schema/visitor aspect.
- Annotating with notes about built-in use cases (like concurrent processing in arrays or composition policies in custom pipelines) to help developers quickly grasp the design rationale.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Input & Core Types
    subgraph "Layer 1: Input & Core Types"
        A["Input Data"]:::input
        CT1["Types"]:::core
        CT2["Type Registry"]:::core
        A -->|"feeds"| CT1
        CT1 -->|"registers"| CT2
    end

    %% Layer 2: Processing (Composable Steps & Pipelines)
    subgraph "Layer 2: Processing"
        P["Plumb::Pipeline"]:::pipeline
        S["Plumb::Step"]:::pipeline
        C["Plumb::Composable"]:::pipeline
        CT1 -->|"transforms"| P
        P -->|"executes"| S
        P -->|"integrates with"| C
    end

    %% Layer 3: Composite Types & Policies
    subgraph "Layer 3: Composite Types & Policies"
        Comp1["Types::Hash"]:::composite
        Comp2["Types::Array"]:::composite
        Comp3["Types::Tuple"]:::composite
        Comp4["Types::Stream"]:::composite
        Pol["Custom Policies"]:::policy
        CT1 -->|"validates"| Comp1
        CT1 -->|"validates"| Comp2
        CT1 -->|"validates"| Comp3
        CT1 -->|"validates"| Comp4
        CT1 -->|"applies"| Pol
    end

    %% Layer 4: Visitors & Support
    subgraph "Layer 4: Visitors & Support"
        V["Plumb::JSONSchemaVisitor"]:::visitor
        VH["Visitor Handlers"]:::visitor
        P -->|"generatesSchema"| V
        V -->|"uses"| VH
    end

    %% Layer 5: Output
    subgraph "Layer 5: Output"
        Out["Validated/Transformed Output"]:::output
        P -->|"results"| Out
        Comp1 -->|"outputs"| Out
        Comp2 -->|"outputs"| Out
        Comp3 -->|"outputs"| Out
        Comp4 -->|"outputs"| Out
        Pol -->|"enriches"| Out
    end

    %% Supporting Directories (Benchmarks, Examples, Specs)
    subgraph "Supporting Directories"
        BD["Benchmarks"]:::support
        EX["Examples"]:::support
        SP["Specs"]:::support
    end

    %% Click Events
    click CT1 "https://github.com/ismasan/plumb/blob/main/lib/plumb/types.rb"
    click CT2 "https://github.com/ismasan/plumb/blob/main/lib/plumb/type_registry.rb"
    click P "https://github.com/ismasan/plumb/blob/main/lib/plumb/pipeline.rb"
    click S "https://github.com/ismasan/plumb/blob/main/lib/plumb/step.rb"
    click C "https://github.com/ismasan/plumb/blob/main/lib/plumb/composable.rb"
    click Comp1 "https://github.com/ismasan/plumb/blob/main/lib/plumb/hash_class.rb"
    click Comp2 "https://github.com/ismasan/plumb/blob/main/lib/plumb/array_class.rb"
    click Comp3 "https://github.com/ismasan/plumb/blob/main/lib/plumb/tuple_class.rb"
    click Comp4 "https://github.com/ismasan/plumb/blob/main/lib/plumb/stream_class.rb"
    click Pol "https://github.com/ismasan/plumb/blob/main/lib/plumb/policies.rb"
    click V "https://github.com/ismasan/plumb/blob/main/lib/plumb/json_schema_visitor.rb"
    click VH "https://github.com/ismasan/plumb/blob/main/lib/plumb/visitor_handlers.rb"
    click BD "https://github.com/ismasan/plumb/tree/main/bench"
    click EX "https://github.com/ismasan/plumb/tree/main/examples"
    click SP "https://github.com/ismasan/plumb/tree/main/spec"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#ccf,stroke:#333,stroke-width:2px;
    classDef composite fill:#cfc,stroke:#333,stroke-width:2px;
    classDef policy fill:#fc9,stroke:#333,stroke-width:2px;
    classDef visitor fill:#cff,stroke:#333,stroke-width:2px;
    classDef support fill:#eee,stroke:#333,stroke-dasharray: 5,5;
    classDef output fill:#ff9,stroke:#333,stroke-width:2px;
    classDef input fill:#c9f,stroke:#333,stroke-width:2px;
```
