# dobiasd/enterprython architecture

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

- Interactive diagram: https://gitdiagram.com/dobiasd/enterprython
- Repository: https://github.com/dobiasd/enterprython

## Overview

##### Project Type and Purpose
- enterprython is an open-source Python library that provides type-based dependency injection (DI) and configuration/value injection to support SOLID and domain-driven designs.
- It is not a full-stack app or microservice suite; rather, it is a reusable DI framework and value-store mechanism for Python applications.

##### File Structure Overview
- Top level:
- setup.py, requirements.txt, LICENSE, README.md – packaging and metadata
- .github/workflows/ci.yml – CI pipeline
- test/ and enterprython/tests.py – test configurations and test suite
- examples/readme_examples.py – sample usage
- why_you_want_formal_dependency_injection_in_python_too.md – motivation article
- Core package: enterprython/
- __init__.py – public API exports (assemble, component, factory, load_config, etc.)
- _inject.py – core container, registry, resolution engine
- py.typed – indicates PEP-561 type hints
- tests.py – package–level test cases

##### Insights from README
- Key components:
- @component decorator, @factory decorator
- assemble() function (entry point to build and run DI)
- Profiles (prod/test) for conditional component binding
- Factory support, singleton vs. non-singleton services
- Service lists (List[T] injection) and manual vs. managed injection mixing
- Free functions as DI clients
- Value store with layered sources (TOML, env vars, CLI args) and value injection via dataclass/attrs + @setting

##### Main Components
a. User Application Layer (in green)
- Client classes or free-function consumers
- Domain classes annotated with @component or @factory
- Optional manual injections passed to assemble()
b. DI Container Layer (in blue)
- assemble() entry point
- ComponentRegistry: holds metadata for all @component and @factory registrations, keyed by type and optionally by profile
- Injector/Resolution Engine: traverses constructor signatures or function parameters, resolves dependencies via registry
- InstanceCache: enforces singleton behavior and non-singleton creation policy
c. Value Store Layer (in orange)
- LoadConfig: merges TOML file(s), environment variables (prefixed), CLI args in precedence order
- ValueStore: lookup API for retrieving config entries by key or path
- Setting decorator logic: binds dataclass/attrs fields to config keys
d. External Resources (in gray)
- Configuration files (config.toml)
- Environment variable namespace
- CLI front-end passing --key=value

##### Relationships and Data Flows
- Application calls assemble(ClientClass, optional overrides) → DI Container
- Container queries ComponentRegistry for ClientClass → sees constructor/factory signature → calls Injector
- Injector resolves each dependency parameter:
- If parameter type is a registered component → create or fetch instance via InstanceCache
- If parameter is a List[T] → fetch all registered implementations of T
- If has default override provided in assemble() → use manual instance
- For any dataclass/attrs components, before instantiation:
- Injector queries ValueStore for each field requiring injection
- ValueStore on first access loads config sources in order: TOML → env → CLI
- Once all dependencies are resolved, Injector calls constructor or factory function, returns fully built object to caller

##### Architectural Patterns and Principles
- Inversion of Control (IoC) via DI container
- Decorator-based registration (component/factory)
- Singleton vs. transient (non-singleton) scope management
- Strategy pattern for profiles (profile filters)
- Composite pattern for service lists injection
- Chain-of-responsibility for config source precedence

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application Layer
    subgraph "User Application Layer"
        direction TB
        Client["Client Classes / Free Functions"]:::user
        Decorators["@component / @factory Decorators"]:::user
        Client -->|"annotation/register"| Decorators
        Examples["Example Usage"]:::user
        Client -->|"calls"| Assemble
    end

    %% Public API entry point
    Assemble["assemble()"]:::container
    ComponentDec["component() / factory()"]:::container
    LoadConfAPI["load_config()"]:::container

    %% DI Container Layer
    subgraph "DI Container Layer"
        direction TB
        Registry["ComponentRegistry"]:::container
        Injector["Injector / Resolution Engine"]:::container
        Cache["InstanceCache"]:::container
        Profile["Profiles (prod/test)"]:::container
        ServiceList["Service List Resolution"]:::container
        SettingDec["@setting Decorator Logic"]:::container

        ComponentDec -->|"register metadata"| Registry
        Registry -->|queries| Injector
        Injector -->|uses| Cache
        Injector -->|applies| Profile
        Injector -->|handles| ServiceList
        Injector -->|handles| SettingDec
    end

    Assemble -->|"builds container"| Registry
    Assemble -->|"builds container"| Injector
    Assemble -->|"builds container"| Cache

    %% Value Store Layer
    subgraph "Value Store Layer"
        direction TB
        LoadConfig["LoadConfig"]:::valuestore
        ValueStore["ValueStore"]:::valuestore
        LoadConfig -->|loads sources| ValueStore
        Injector -->|queries for values| ValueStore
    end

    %% External Resources
    subgraph "External Resources"
        direction TB
        TOML["config.toml"]:::external
        Env["Environment Variables"]:::external
        CLI["CLI Arguments"]:::external
        TOML -->|precedence| LoadConfig
        Env -->|precedence| LoadConfig
        CLI -->|precedence| LoadConfig
    end

    %% Relationships
    Registry -->|"resolve dependency"| Injector
    Injector -->|create/fetch| Cache
    Cache -->|return instance| Client

    %% Annotations
    classDef user fill:#e2f7e1,stroke:#2b8c3e,color:#2b8c3e
    classDef container fill:#e1eef7,stroke:#1f63a3,color:#1f63a3
    classDef valuestore fill:#fde8d6,stroke:#d97706,color:#d97706
    classDef external fill:#f0f0f0,stroke:#6c757d,color:#6c757d

    %% Click Events
    click Examples "https://github.com/dobiasd/enterprython/blob/master/examples/readme_examples.py"
    click Assemble "https://github.com/dobiasd/enterprython/blob/master/enterprython/__init__.py"
    click ComponentDec "https://github.com/dobiasd/enterprython/blob/master/enterprython/__init__.py"
    click LoadConfAPI "https://github.com/dobiasd/enterprython/blob/master/enterprython/__init__.py"
    click _Inject "https://github.com/dobiasd/enterprython/blob/master/enterprython/_inject.py"
    click TOML "https://github.com/dobiasd/enterprython/blob/master/test/config.toml"
    click CI "https://github.com/dobiasd/enterprython/blob/master/.github/workflows/ci.yml"
    click TestsPackage "https://github.com/dobiasd/enterprython/blob/master/enterprython/tests.py"
    click PyTyped "https://github.com/dobiasd/enterprython/blob/master/enterprython/py.typed"
    click TestSuite "https://github.com/dobiasd/enterprython/tree/master/test/"
    click Setup "https://github.com/dobiasd/enterprython/blob/master/setup.py"
    click Requirements "https://github.com/dobiasd/enterprython/blob/master/requirements.txt"
    click Readme "https://github.com/dobiasd/enterprython/blob/master/README.md"
    click License "https://github.com/dobiasd/enterprython/tree/master/LICENSE"
    click Motivation "https://github.com/dobiasd/enterprython/blob/master/why_you_want_formal_dependency_injection_in_python_too.md"
```
