# openai/chz architecture

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

- Interactive diagram: https://gitdiagram.com/openai/chz
- Repository: https://github.com/openai/chz

## Overview

##### Project type and purpose
- Project type: A Python library/tool (open-source) focused on configuration management and command-line parsing.
- Purpose: Provide a declarative object model for configuration, support validation, partial application (“blueprints”), presets, serialization/deserialization, and generate a user-friendly CLI interface.

##### File structure
Top level:
- chz/                ← main Python package
– blueprint/        ← “blueprint” sub-package (core API surface for creating reusable config blueprints)
- _argmap.py      ← mapping CLI args to blueprint fields
- _argv.py        ← parsing argv arrays
- _blueprint.py   ← blueprint class definitions & logic
- _entrypoint.py  ← tying blueprint to an executable entrypoint
- _lazy.py        ← lazy evaluation utilities
- _wildcard.py    ← handling variadic args/fields
– data_model.py     ← declarative object model & immutability support
– field.py          ← field descriptor API
– validators.py     ← validation rules & type checking
– mungers.py        ← data-munging pipeline (transformers)
– factories.py      ← creating instances of the data model from raw inputs
– tiepin.py         ← user-facing CLI entrypoint runner
– universal.py      ← cross-cutting utilities
– util.py           ← general helper functions
- docs/               ← conceptual and user documentation
- tests/              ← unit tests for every major module
- pyproject.toml      ← build & dependency configuration

##### README for additional insights
- Highlights features: quickstart, declarative model, immutability, validation, CLI parsing, help/discoverability, partial application, presets, serialization
- No external runtime (no database, no network services)—all in-process library

##### Elements
– Blue for user-facing components (tiepin.py, blueprint API)
– Green for core engine (factories, data_model, validators, mungers)
– Gray for utilities/support (util, universal, lazy, wildcard)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User-Facing Components"
        tiepin["tiepin.py"]:::blue
        entrypoint["_entrypoint.py"]:::blue
    end

    subgraph "Argument Parsing"
        argv["_argv.py"]:::green
        argmap["_argmap.py"]:::green
    end

    blueprint["_blueprint.py"]:::blue

    subgraph "Data Model Layer"
        datamodel["data_model.py"]:::green
        field["field.py"]:::green
    end

    factories["factories.py"]:::green
    mungers["mungers.py"]:::green
    validators["validators.py"]:::green
    serialization["universal.py"]:::green

    subgraph "Utilities"
        util["util.py"]:::gray
        lazy["_lazy.py"]:::gray
        wildcard["_wildcard.py"]:::gray
    end

    tiepin -->|"invoke CLI"| entrypoint
    entrypoint -->|"read sys.argv"| argv
    argv -->|"raw args"| argmap
    argmap -->|"parsed fields"| blueprint
    blueprint -->|"instantiate model"| factories
    factories -->|"create instances"| mungers
    mungers -->|"apply transformations"| validators
    validators -->|"enforce rules"| serialization
    serialization -->|"serialized output"| serialization

    click tiepin "https://github.com/openai/chz/blob/main/chz/tiepin.py"
    click entrypoint "https://github.com/openai/chz/blob/main/chz/blueprint/_entrypoint.py"
    click argv "https://github.com/openai/chz/blob/main/chz/blueprint/_argv.py"
    click argmap "https://github.com/openai/chz/blob/main/chz/blueprint/_argmap.py"
    click blueprint "https://github.com/openai/chz/blob/main/chz/blueprint/_blueprint.py"
    click datamodel "https://github.com/openai/chz/blob/main/chz/data_model.py"
    click field "https://github.com/openai/chz/blob/main/chz/field.py"
    click factories "https://github.com/openai/chz/blob/main/chz/factories.py"
    click validators "https://github.com/openai/chz/blob/main/chz/validators.py"
    click mungers "https://github.com/openai/chz/blob/main/chz/mungers.py"
    click serialization "https://github.com/openai/chz/blob/main/chz/universal.py"
    click util "https://github.com/openai/chz/blob/main/chz/util.py"
    click lazy "https://github.com/openai/chz/blob/main/chz/blueprint/_lazy.py"
    click wildcard "https://github.com/openai/chz/blob/main/chz/blueprint/_wildcard.py"

    classDef blue fill:#ade8f4,stroke:#03045e,color:#000
    classDef green fill:#caf0f8,stroke:#0077b6,color:#000
    classDef gray fill:#e9ecef,stroke:#495057,color:#000
```
