# cuyz/valinor architecture

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

- Interactive diagram: https://gitdiagram.com/cuyz/valinor
- Repository: https://github.com/cuyz/valinor

## Overview

##### Project type and purpose
- This is an open-source PHP library (cuyz/valinor) providing two main capabilities:
- Mapping raw inputs (arrays, JSON, YAML) into fully-typed PHP objects with validation.
- Normalizing PHP objects or data to various output formats (JSON, CSV, etc.).
- It’s not a web app but a core library, organized into several cohesive modules (Mapper, Normalizer, Type system, Cache, Definition, Utility).

##### High-level architecture components
a. Entry points
- MapperBuilder → produces a Mapper instance.
- NormalizerBuilder → produces a Normalizer instance.
b. Input sources
- Source implementations: JsonSource, YamlSource, FileSource.
- Modifiers: CamelCaseKeys, PathMapping.
c. Definition & type resolution
- Definition Repository (Reflection vs. Compiled/Cache).
- Type Resolver components (function, parameter, property).
- TypeParser & Lexer → builds Type objects (UnionType, GenericType, etc.).
d. Mapping pipeline
- Mapper calls TreeMapper → builds a tree of Node objects using NodeBuilders (ArrayNodeBuilder, ObjectNodeBuilder, UnionNodeBuilder…).
- Converters (AsConverter) and ObjectBuilders map nodes to PHP values or objects, handling constructors, attributes, error signaling.
- Error messages assembled via MessageBuilder and Formatters.
e. Normalization pipeline
- Normalizer uses TransformerCompiler to compile transformer definitions.
- TransformerContainer holds (JsonFormatter, DateTimeFormatter, etc.).
- RecursiveTransformer traverses objects/data to produce the normalized output.
f. Caching & warmup
- Cache implementations: FileSystemCache, RuntimeCache, KeySanitizerCache.
- Warmup service pre-compiles definitions/normalizers to PHP files in cache.
g. Utility & support
- Container & Settings classes for DI and configuration.
- Reflection helpers, String formatters, Value dumper.

##### Relationships and data flow
- Raw input (JSON/YAML/array) → Source → MapperBuilder → Mapper → Definition Repository → TreeMapper
→ NodeBuilders + Converters + ObjectBuilders → Typed PHP object
→ (on failure) MappingError + ErrorMessage → Developer
- PHP object/data → NormalizerBuilder → Normalizer → TransformerCompiler → RecursiveTransformer
→ Formatter → Output format (string, stream).
- Definition and transformer compilation results stored in Cache; Warmup service can generate cached code before runtime.

##### Architectural patterns & design principles
- Modular layers: Source → Mapper → Tree → Builders → Objects/Values
- Separation of concerns: mapping vs. normalization vs. typing vs. caching
- Pluggable converters/transformers via container and attribute-based configuration
- Reflection + compile-time caching for performance
- Extensive use of the Builder pattern (MapperBuilder, NodeBuilder, TransformerDefinitionBuilder)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Entry Points
    subgraph "Entry Points"
        MB["MapperBuilder"]:::entry
        NB["NormalizerBuilder"]:::entry
    end

    %% Input Sources
    subgraph "Input Sources"
        JSON["JsonSource"]:::source
        YAML["YamlSource"]:::source
        FILE["FileSource"]:::source
        CC["CamelCaseKeys"]:::modifier
        PM["PathMapping"]:::modifier
    end

    %% Mapping Core
    subgraph "Mapping Core" 
        TM["TreeMapper"]:::mapping
        NBld["NodeBuilders"]:::mapping
        AC["AsConverter"]:::mapping
        OB["ObjectBuilders"]:::mapping
        MBld["MessageBuilder & Formatters"]:::mapping
    end

    %% Object Output
    OBJ["Typed PHP Object"]:::output
    ERR["MappingError + ErrorMessage"]:::error

    %% Normalization Core
    subgraph "Normalization Core"
        TDB["TransformerDefinitionBuilder"]:::normalize
        RT["RecursiveTransformer"]:::normalize
        TC["TransformerContainer"]:::normalize
        JF["JsonFormatter"]:::normalize
    end
    OUT["Normalized Output"]:::output

    %% Definition & Type Layer
    subgraph "Definition & Type System" 
        RR["ReflectionRepo"]:::definition
        CR["CompiledRepo"]:::definition
        TR["TypeResolver"]:::definition
        TP["TypeParser"]:::definition
        TL["TypeLexer"]:::definition
        PF["TypeParserFactory"]:::definition
    end

    %% Cache & Warmup
    subgraph "Cache & Warmup"
        FSC["FileSystemCache"]:::cache
        RC["RuntimeCache"]:::cache
        KC["KeySanitizerCache"]:::cache
        WS["WarmupService"]:::cache
    end

    %% Utilities
    subgraph "Utilities"
        CNT["Container"]:::util
        SET["Settings"]:::util
        RH["ReflectionHelpers"]:::util
        SF["StringFormatter"]:::util
        VD["ValueDumper"]:::util
    end

    %% Flows
    JSON --> MB
    YAML --> MB
    FILE --> MB
    CC --> MB
    PM --> MB

    MB -->|"map() call"| TM
    TM --> NBld
    NBld --> AC
    AC --> OB
    OB --> OBJ
    TM --> MBld
    MBld --> ERR

    OBJ --> NB
    NB --> TDB
    TDB --> RT
    RT --> TC
    TC --> JF
    JF --> OUT

    %% Definition & Type connections
    MB --> RR
    RR --> TR
    CR --> TR
    MB --> CR
    TR --> TM
    TR --> NBld
    TDB --> PF
    PF --> TP
    TP --> TL

    %% Cache & Warmup connections
    RR --> FSC
    CR --> RC
    TDB --> RC
    FSC --> WS
    RC --> WS

    %% Utilities references
    MB --> CNT
    MB --> SET
    TM --> RH
    MBld --> SF
    MBld --> VD
    NB --> CNT

    %% Click Events
    click MB "https://github.com/cuyz/valinor/blob/master/src/MapperBuilder.php"
    click NB "https://github.com/cuyz/valinor/blob/master/src/NormalizerBuilder.php"
    click JSON "https://github.com/cuyz/valinor/blob/master/src/Mapper/Source/JsonSource.php"
    click YAML "https://github.com/cuyz/valinor/blob/master/src/Mapper/Source/YamlSource.php"
    click FILE "https://github.com/cuyz/valinor/blob/master/src/Mapper/Source/FileSource.php"
    click CC "https://github.com/cuyz/valinor/blob/master/src/Mapper/Source/Modifier/CamelCaseKeys.php"
    click PM "https://github.com/cuyz/valinor/blob/master/src/Mapper/Source/Modifier/PathMapping.php"
    click RR "https://github.com/cuyz/valinor/tree/master/src/Definition/Repository/Reflection"
    click CR "https://github.com/cuyz/valinor/blob/master/src/Definition/Repository/Cache/CompiledClassDefinitionRepository.php"
    click CR "https://github.com/cuyz/valinor/blob/master/src/Definition/Repository/Cache/CompiledFunctionDefinitionRepository.php"
    click TR "https://github.com/cuyz/valinor/tree/master/src/Definition/Repository/Reflection/TypeResolver"
    click TP "https://github.com/cuyz/valinor/blob/master/src/Type/Parser/TypeParser.php"
    click TL "https://github.com/cuyz/valinor/blob/master/src/Type/Parser/Lexer/TypeLexer.php"
    click PF "https://github.com/cuyz/valinor/blob/master/src/Type/Parser/Factory/TypeParserFactory.php"
    click TM "https://github.com/cuyz/valinor/blob/master/src/Mapper/TreeMapper.php"
    click NBld "https://github.com/cuyz/valinor/tree/master/src/Mapper/Tree/Builder"
    click AC "https://github.com/cuyz/valinor/blob/master/src/Mapper/AsConverter.php"
    click OB "https://github.com/cuyz/valinor/tree/master/src/Mapper/Object"
    click MBld "https://github.com/cuyz/valinor/blob/master/src/Mapper/Tree/Message/MessageBuilder.php"
    click JF "https://github.com/cuyz/valinor/blob/master/src/Normalizer/Formatter/JsonFormatter.php"
    click TDB "https://github.com/cuyz/valinor/blob/master/src/Normalizer/Transformer/Compiler/TransformerDefinitionBuilder.php"
    click RT "https://github.com/cuyz/valinor/blob/master/src/Normalizer/Transformer/RecursiveTransformer.php"
    click TC "https://github.com/cuyz/valinor/blob/master/src/Normalizer/Transformer/TransformerContainer.php"
    click FSC "https://github.com/cuyz/valinor/blob/master/src/Cache/FileSystemCache.php"
    click RC "https://github.com/cuyz/valinor/blob/master/src/Cache/RuntimeCache.php"
    click KC "https://github.com/cuyz/valinor/blob/master/src/Cache/KeySanitizerCache.php"
    click WS "https://github.com/cuyz/valinor/blob/master/src/Cache/Warmup/RecursiveCacheWarmupService.php"
    click CNT "https://github.com/cuyz/valinor/blob/master/src/Library/Container.php"
    click SET "https://github.com/cuyz/valinor/blob/master/src/Library/Settings.php"
    click RH "https://github.com/cuyz/valinor/tree/master/src/Utility/Reflection"
    click SF "https://github.com/cuyz/valinor/blob/master/src/Utility/String/StringFormatter.php"
    click VD "https://github.com/cuyz/valinor/blob/master/src/Utility/ValueDumper.php"

    %% Styles
    classDef entry fill:#f9f,stroke:#333,stroke-width:1px
    classDef source fill:#cff,stroke:#036,stroke-width:1px
    classDef modifier fill:#cfc,stroke:#363,stroke-width:1px
    classDef mapping fill:#bbf,stroke:#00f,stroke-width:1px
    classDef normalize fill:#bfb,stroke:#0a0,stroke-width:1px
    classDef definition fill:#fcf,stroke:#f0f,stroke-width:1px
    classDef cache fill:#ddd,stroke:#888,stroke-width:1px
    classDef util fill:#eee,stroke:#666,stroke-width:1px
    classDef output fill:#ffe,stroke:#f90,stroke-width:1px
    classDef error fill:#fdd,stroke:#d00,stroke-width:1px
```
