# reagento/adaptix architecture

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

- Interactive diagram: https://gitdiagram.com/reagento/adaptix
- Repository: https://github.com/reagento/adaptix

## Overview

##### Project type and purpose
- This is a Python open-source library (“adaptix”) providing an extremely flexible and configurable data model conversion system (loading, dumping, and model-to-model conversion).
- It is not a full-stack application but a modular library with a clear public API, rich internal subsystems, and integrations with external model frameworks (dataclasses, attrs, pydantic, SQLAlchemy, msgspec).

##### File structure
- Top-level directories:
- src/adaptix – the core Python package, subdivided into public modules and a large `_internal` package.
- tests, benchmarks, docs, examples, scripts – supporting code, not part of the runtime system.
- Key internal subdirectories under `src/adaptix/_internal`:
- code_tools – compilation and code‐generation utilities
- conversion – “model A → model B” conversion engine
- model_tools – introspection of a variety of model types
- morphing – JSON/schema loader & dumper generator
- provider – request dispatch, schema overlay, value providers
- retort – central mediator, routing, error handling
- type_tools – type normalization and resolution
- Public modules under `src/adaptix`:
- retort.py – main entry point (`Retort`)
- conversion – public API for converters (`get_converter`)
- provider, load_error, struct_trail, type_tools – supporting APIs
- integrations – adapters for pydantic, SQLAlchemy, msgspec

##### README for additional insights
- Public API revolves around two use cases:
a) instantiating a global `Retort` to `load`/`dump` arbitrary models ↔ Python dicts
b) calling `get_converter` to transform one model type into another
- Emphasis on performance, extensibility, and separation of concerns

a. Main components to include:
- Public API layer
– `Retort` (loading/dumping mediator)
– `get_converter` (conversion factory)
- Internal subsystems
– Retort subsystem (routers, request bus, error renderer)
– Conversion subsystem (facade, code_generator, coercer/provider)
– Morphing subsystem (loader/provider, dumper/provider, JSON schema)
– Model tools subsystem (introspection for dataclass, attrs, Pydantic, SQLA, NamedTuple, TypedDict, msgspec)
– Provider subsystem (value providers, overlay schema, loc_stack filtering)
– Code tools subsystem (AST templater, code_builder, compiler)
– Type tools subsystem (type normalization, generic resolution)
- External integrations
– Dataclasses (built-in)
– attrs, Pydantic, SQLAlchemy, msgspec
- Data flow / dependencies
– Application → Public API → Retort / Converter → Internal subsystems → Integration adapters → Model frameworks
– Code generation path: Conversion → Code tools → Generated loader/dumper code → Morphing
b. Relationships and interactions
– Retort uses Provider + Model tools + Morphing under the hood
– Conversion subsystem orchestrates code_tools + provider + type_tools to produce conversion functions
– Morphing subsystem interacts with JSON/schema and provider subsystems to load/dump raw data
– Integration adapters plug into Model tools and Morphing subsystems
c. Architectural patterns and principles
– Single Responsibility Principle (each subsystem has a focused domain)
– Mediator pattern (`Retort` as central orchestrator)
– Facade pattern (conversion façade, morphing façade)
– Plugin architecture (integration modules discoverable under `integrations/…`)
– Code generation pipeline (AST templater → code builder → compiler)
d. Technologies and frameworks
– Python packaging and modules
– AST‐based code generation
– Model frameworks (dataclasses, attrs, Pydantic, SQLAlchemy, msgspec)

##### Elements
- Clear labels for: Public API, Retort subsystem, Conversion subsystem, Morphing subsystem, Model tools, Provider, Code tools, Type tools, Integrations
- Gray for internal subsystems
- Green for code generation/morph components
- Orange for integration adapters/external models

##### Detail
- Explicitly show each internal package as a separate component
- Flow of data and code (e.g. how a `load(...)` call propagates through retort → provider → morphing → model construction)
- Avoid lumping all internals together; break down into at least Retort, Conversion, Morphing, ModelTools, Provider, CodeTools, TypeTools, Integrations

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef public fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef internal fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef code fill:#DFF0D8,stroke:#333,stroke-width:1px
    classDef integration fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#333,stroke-width:1px

    Application["Application"]:::external

    subgraph "Public API"
        Public_Retort["Retort"]:::public
        Public_GetConverter["get_converter"]:::public
        Public_ProviderAPI["provider API"]:::public
        Public_LoadError["load_error"]:::public
        Public_StructTrail["struct_trail"]:::public
        Public_TypeToolsAPI["type_tools API"]:::public
        Public_IntegrationsAPI["integrations"]:::public
    end

    subgraph "Internal Subsystems"
        RetortSS["Retort Subsystem"]:::internal
        ConversionSS["Conversion Subsystem"]:::internal
        MorphingSS["Morphing Subsystem"]:::internal
        ModelToolsSS["Model Tools"]:::internal
        ProviderSS["Provider Subsystem"]:::internal
        CodeToolsSS["Code Tools"]:::code
        TypeToolsSS["Type Tools"]:::internal
    end

    subgraph "Integrations"
        Int_Msgspec["msgspec"]:::integration
        Int_Pydantic["pydantic"]:::integration
        Int_SQLAlchemy["SQLAlchemy"]:::integration
    end

    Application --> Public_Retort
    Application --> Public_GetConverter
    Application --> Public_ProviderAPI
    Application --> Public_LoadError
    Application --> Public_StructTrail
    Application --> Public_TypeToolsAPI
    Application --> Public_IntegrationsAPI

    Public_Retort --> RetortSS
    Public_GetConverter --> ConversionSS
    Public_ProviderAPI --> ProviderSS
    Public_TypeToolsAPI --> TypeToolsSS
    Public_IntegrationsAPI --> Int_Msgspec
    Public_IntegrationsAPI --> Int_Pydantic
    Public_IntegrationsAPI --> Int_SQLAlchemy

    RetortSS --> ProviderSS
    RetortSS --> ModelToolsSS
    RetortSS --> MorphingSS

    ConversionSS --> CodeToolsSS
    ConversionSS --> ProviderSS
    ConversionSS --> TypeToolsSS

    CodeToolsSS --> MorphingSS
    MorphingSS --> ModelToolsSS

    Int_Msgspec --> ModelToolsSS
    Int_Msgspec --> MorphingSS
    Int_Pydantic --> ModelToolsSS
    Int_Pydantic --> MorphingSS
    Int_SQLAlchemy --> ModelToolsSS
    Int_SQLAlchemy --> MorphingSS

    click Public_Retort "https://github.com/reagento/adaptix/blob/main/src/adaptix/retort.py"
    click Public_GetConverter "https://github.com/reagento/adaptix/blob/main/src/adaptix/conversion/__init__.py"
    click Public_ProviderAPI "https://github.com/reagento/adaptix/blob/main/src/adaptix/provider/__init__.py"
    click Public_LoadError "https://github.com/reagento/adaptix/blob/main/src/adaptix/load_error.py"
    click Public_StructTrail "https://github.com/reagento/adaptix/blob/main/src/adaptix/struct_trail.py"
    click Public_TypeToolsAPI "https://github.com/reagento/adaptix/blob/main/src/adaptix/type_tools/__init__.py"
    click Public_IntegrationsAPI "https://github.com/reagento/adaptix/tree/main/src/adaptix/integrations/"
    click RetortSS "https://github.com/reagento/adaptix/tree/main/src/adaptix/_internal/retort/"
    click ConversionSS "https://github.com/reagento/adaptix/tree/main/src/adaptix/_internal/conversion/"
    click MorphingSS "https://github.com/reagento/adaptix/tree/main/src/adaptix/_internal/morphing/"
    click ModelToolsSS "https://github.com/reagento/adaptix/tree/main/src/adaptix/_internal/model_tools/"
    click ProviderSS "https://github.com/reagento/adaptix/tree/main/src/adaptix/_internal/provider/"
    click CodeToolsSS "https://github.com/reagento/adaptix/tree/main/src/adaptix/_internal/code_tools/"
    click TypeToolsSS "https://github.com/reagento/adaptix/tree/main/src/adaptix/_internal/type_tools/"
    click Int_Msgspec "https://github.com/reagento/adaptix/blob/main/src/adaptix/integrations/msgspec/__init__.py"
    click Int_Pydantic "https://github.com/reagento/adaptix/blob/main/src/adaptix/integrations/pydantic/__init__.py"
    click Int_SQLAlchemy "https://github.com/reagento/adaptix/blob/main/src/adaptix/integrations/sqlalchemy/__init__.py"
```
