# maldoinc/wireup architecture

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

- Interactive diagram: https://gitdiagram.com/maldoinc/wireup
- Repository: https://github.com/maldoinc/wireup

## Overview

##### Project Type and Purpose
- This is a Python library (Wireup) providing a dependency-injection (DI) framework for Python 3.8+.
- It is framework-agnostic but offers built-in integrations for FastAPI, Django, Flask and AIOHTTP.
- Primary use case: allow authors to declare & manage services (singletons, scoped, transient) and inject them into applications or functions in a type-safe, performant way.

##### File Structure Analysis
- Top-level artifacts:
- Makefile, tox.ini, GitHub Actions workflows (.github/workflows) for CI and coverage.
- pyproject.toml for packaging.
- readme.md & docs/ for user documentation (MkDocs).
- test/ for unit and integration tests.
- wireup/ containing the library’s source code.
- Library internals (wireup/):
- _annotations, _decorators, _discovery, errors.py – core DI constructs.
- integration/ – adapters for FastAPI, Django, Flask, AIOHTTP.
- ioc/ – service registry, container implementations (sync/async), override manager, parameter handling, validation.
- Tests mirror integrations and core functionality:
- test/unit – core container, binding, override, scope.
- test/integration – sample apps per framework verifying DI behavior.

##### README Insights
- Emphasizes key DI features: simple service decorator, function injection, abstract interfaces, managed lifetimes, sync/async factory support, safety via static checks.
- Shows code snippets for service registration, container creation, function injection, overriding for tests, framework setup.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Consumer Code"
        ConsumerApp["Consumer App"]:::consumer
    end

    subgraph "Wireup API Layer"
        Decorators["_decorators.py"]:::api
        Annotations["_annotations.py"]:::api
        Discovery["_discovery.py"]:::api
    end

    subgraph "Core DI Constructs"
        Errors["errors.py"]:::core
        AsyncToSync["_async_to_sync.py"]:::core
    end

    subgraph "IOC Container Core"
        ServiceRegistry["service_registry.py"]:::core
        Parameter["parameter.py"]:::core
        OverrideManager["override_manager.py"]:::core
        Validation["validation.py"]:::core
        Util["util.py"]:::core
        Types["types.py"]:::core
        ExitStack["_exit_stack.py"]:::core
    end

    subgraph "Container Implementations"
        BaseContainer["base_container.py"]:::impl
        SyncContainer["sync_container.py"]:::impl
        AsyncContainer["async_container.py"]:::impl
    end

    subgraph "Integration Adapters"
        FastAPIAdapter["fastapi.py"]:::integration
        FlaskAdapter["flask.py"]:::integration
        AioHTTPAdapter["aiohttp.py"]:::integration
        DjangoAdapter["apps.py"]:::integration
    end

    subgraph "Framework Runtime"
        FastAPI["FastAPI"]:::external
        Flask["Flask"]:::external
        Django["Django"]:::external
        AIOHTTP["AIOHTTP"]:::external
    end

    subgraph "Docs & CI"
        MkDocs["mkdocs.yml"]:::docs
        DocsPages["docs/pages/"]:::docs
        UnitTests["test/unit/"]:::docs
        IntegrationTests["test/integration/"]:::docs
        CI[".github/workflows/"]:::docs
    end

    ConsumerApp -->|"register/inject"| Decorators
    ConsumerApp -->|"register/inject"| Annotations
    ConsumerApp -->|"discover services"| Discovery

    Decorators --> ServiceRegistry
    Annotations --> ServiceRegistry
    Discovery --> ServiceRegistry

    ServiceRegistry --> Validation
    ServiceRegistry --> Parameter
    ServiceRegistry --> OverrideManager
    Validation --> BaseContainer
    Parameter --> BaseContainer
    OverrideManager --> BaseContainer
    Util --> BaseContainer
    Types --> BaseContainer
    ExitStack --> BaseContainer

    Errors --> ServiceRegistry
    AsyncToSync --> BaseContainer

    BaseContainer --> SyncContainer
    BaseContainer --> AsyncContainer
    SyncContainer --> ExitStack
    AsyncContainer --> ExitStack

    FastAPI --> FastAPIAdapter
    Flask --> FlaskAdapter
    Django --> DjangoAdapter
    AIOHTTP --> AioHTTPAdapter

    FastAPIAdapter --> SyncContainer
    FastAPIAdapter --> AsyncContainer
    FlaskAdapter --> SyncContainer
    FlaskAdapter --> AsyncContainer
    AioHTTPAdapter --> SyncContainer
    AioHTTPAdapter --> AsyncContainer
    DjangoAdapter --> SyncContainer
    DjangoAdapter --> AsyncContainer

    OverrideManager --> UnitTests
    FastAPIAdapter --> IntegrationTests
    FlaskAdapter --> IntegrationTests
    AioHTTPAdapter --> IntegrationTests
    DjangoAdapter --> IntegrationTests

    click Decorators "https://github.com/maldoinc/wireup/blob/master/wireup/_decorators.py"
    click Annotations "https://github.com/maldoinc/wireup/blob/master/wireup/_annotations.py"
    click Discovery "https://github.com/maldoinc/wireup/blob/master/wireup/_discovery.py"
    click Errors "https://github.com/maldoinc/wireup/blob/master/wireup/errors.py"
    click AsyncToSync "https://github.com/maldoinc/wireup/blob/master/wireup/_async_to_sync.py"
    click ServiceRegistry "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/service_registry.py"
    click Parameter "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/parameter.py"
    click OverrideManager "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/override_manager.py"
    click Validation "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/validation.py"
    click Util "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/util.py"
    click Types "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/types.py"
    click ExitStack "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/_exit_stack.py"
    click BaseContainer "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/container/base_container.py"
    click SyncContainer "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/container/sync_container.py"
    click AsyncContainer "https://github.com/maldoinc/wireup/blob/master/wireup/ioc/container/async_container.py"
    click FastAPIAdapter "https://github.com/maldoinc/wireup/blob/master/wireup/integration/fastapi.py"
    click FlaskAdapter "https://github.com/maldoinc/wireup/blob/master/wireup/integration/flask.py"
    click AioHTTPAdapter "https://github.com/maldoinc/wireup/blob/master/wireup/integration/aiohttp.py"
    click DjangoAdapter "https://github.com/maldoinc/wireup/blob/master/wireup/integration/django/apps.py"
    click MkDocs "https://github.com/maldoinc/wireup/blob/master/docs/mkdocs.yml"
    click DocsPages "https://github.com/maldoinc/wireup/tree/master/docs/pages/"
    click UnitTests "https://github.com/maldoinc/wireup/tree/master/test/unit/"
    click IntegrationTests "https://github.com/maldoinc/wireup/tree/master/test/integration/"
    click CI "https://github.com/maldoinc/wireup/tree/master/.github/workflows/"

    classDef consumer fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#ccf,stroke:#333,stroke-width:1px
    classDef core fill:#cfc,stroke:#333,stroke-width:1px
    classDef impl fill:#fcf,stroke:#333,stroke-width:1px
    classDef integration fill:#cff,stroke:#333,stroke-width:1px
    classDef external fill:#ffc,stroke:#333,stroke-width:1px
    classDef docs fill:#eee,stroke:#333,stroke-width:1px
```
