# dog-egg/zangar architecture

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

- Interactive diagram: https://gitdiagram.com/dog-egg/zangar
- Repository: https://github.com/dog-egg/zangar

## Overview

##### Project type and purpose
- Project type: an open-source Python library/tool (no standalone frontend or service)
- Purpose: expose a programmable API for defining type schemas, converting between representations, and compiling those types into OpenAPI (and other) artifacts

##### File structure
- Top-level “src/zangar” folder holds all runtime code.
– _core.py: core entry points / orchestrator
– _functional.py: functional‐style facade / helpers
– _conversions.py: routines to convert between Python data and schema representations
– _messages.py: centralized message templates / error messages
– compilation.py: logic to compile type definitions into output artifacts (e.g., OpenAPI JSON)
– exceptions.py: custom exception classes
– utils/version.py: version lookup, etc.
– _types/ subpackage: classes modeling primitives, dataclasses, compound structures, and base interfaces
- “docs/” contains Sphinx sources (API docs, type schemas, OpenAPI guide)
- “tests/” contains unit tests, OpenAPI integration tests, type‐checking tests

##### README insights
- Minimal README with link to full documentation
- Repository badges for CI and coverage
- Emphasis on OpenAPI support in docs

##### Main components & relationships
a. Public API layer:
– Modules: zangar._core and zangar._functional
– Exposed to library consumers
b. Type system:
– zangar._types (base.py, primitives.py, dataclass.py, structures.py)
– Models user-defined or built-in types
c. Conversion engine:
– zangar._conversions
– Translates Python values ↔ intermediate schema representations
d. Compilation engine:
– zangar.compilation
– Takes type definitions + conversions, emits OpenAPI specs or other target artifacts
e. Messaging & exceptions:
– zangar._messages for user-facing strings
– zangar.exceptions for control flow and error handling
f. Utilities:
– zangar.utils.version

1. Consumer calls Public API → Core/Functional facade
2. Core invokes Conversion engine (to normalize inputs)
3. Core passes normalized types to Compilation engine
4. Compilation engine produces schema JSON/YAML
5. Any errors trigger Exceptions, formatted via Messages module

##### Architectural patterns & technologies
- Layered modular architecture – clear separation of API, domain models (types), conversion logic, and compilation
- Functional facade for ergonomic API (seen in _functional.py)
- Domain model pattern in _types
- Pluggable compilation targets (via compilation.py)
- Sphinx for docs generation, pytest for tests, GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    title["Zangar Library Architecture"]:::title

    Consumer["Consumer Code"]:::external

    subgraph "Public API Layer"
        Core["Core (_core.py)"]:::api
        Functional["Functional Facade (_functional.py)"]:::api
    end

    subgraph "Processing Engines"
        Conversion["Conversion Engine (_conversions.py)"]:::process
        Compilation["Compilation Engine (compilation.py)"]:::process
    end

    subgraph "Type System"
        Base["Base Interfaces (base.py)"]:::domain
        Primitives["Primitives (primitives.py)"]:::domain
        Dataclass["Dataclasses (dataclass.py)"]:::domain
        Structures["Structures (structures.py)"]:::domain
    end

    subgraph "Cross-cutting Modules"
        Exceptions["Exceptions (exceptions.py)"]:::cross
        Messages["Messages (_messages.py)"]:::cross
        Version["Version Utility (version.py)"]:::util
    end

    subgraph "Project Resources"
        Docs["Documentation Sources (docs/)"]:::external
        Tests["Tests Suite (tests/)"]:::external
    end

    Consumer -->|"calls"| Core
    Consumer -->|"calls"| Functional

    Core -->|"normalize inputs"| Conversion
    Functional -->|"normalize inputs"| Conversion

    Conversion -->|"schema definitions"| Base
    Conversion --> Base
    Conversion --> Primitives
    Conversion --> Dataclass
    Conversion --> Structures

    Core -->|"type definitions"| Compilation
    Functional -->|"type definitions"| Compilation
    Base -->|"model types"| Compilation
    Primitives -->|"model types"| Compilation
    Dataclass -->|"model types"| Compilation
    Structures -->|"model types"| Compilation

    Conversion -->|"error"| Exceptions
    Compilation -->|"error"| Exceptions
    Exceptions -->|"format"| Messages
    Messages -->|"output error"| Consumer

    click Core "https://github.com/dog-egg/zangar/blob/main/src/zangar/_core.py"
    click Functional "https://github.com/dog-egg/zangar/blob/main/src/zangar/_functional.py"
    click Conversion "https://github.com/dog-egg/zangar/blob/main/src/zangar/_conversions.py"
    click Compilation "https://github.com/dog-egg/zangar/blob/main/src/zangar/compilation.py"
    click Messages "https://github.com/dog-egg/zangar/blob/main/src/zangar/_messages.py"
    click Exceptions "https://github.com/dog-egg/zangar/blob/main/src/zangar/exceptions.py"
    click Base "https://github.com/dog-egg/zangar/blob/main/src/zangar/_types/base.py"
    click Primitives "https://github.com/dog-egg/zangar/blob/main/src/zangar/_types/primitives.py"
    click Dataclass "https://github.com/dog-egg/zangar/blob/main/src/zangar/_types/dataclass.py"
    click Structures "https://github.com/dog-egg/zangar/blob/main/src/zangar/_types/structures.py"
    click Version "https://github.com/dog-egg/zangar/blob/main/src/zangar/utils/version.py"
    click Docs "https://github.com/dog-egg/zangar/tree/main/docs/"
    click Tests "https://github.com/dog-egg/zangar/tree/main/tests/"

    classDef title fill:#ffffff,stroke:none,font-size:24px,font-weight:bold
    classDef external fill:#f0f0f0,stroke:#bbb,stroke-width:1px
    classDef api fill:#cfe2f3,stroke:#6fa8dc,stroke-width:2px,color:#000
    classDef process fill:#f9cb9c,stroke:#e69138,stroke-width:2px,color:#000
    classDef domain fill:#d9ead3,stroke:#93c47d,stroke-width:2px,color:#000
    classDef util fill:#e7e6e6,stroke:#a5a5a5,stroke-width:2px,color:#000
    classDef cross fill:#f4cccc,stroke:#cc0000,stroke-width:2px,color:#000
```
