# yakimka/picodi architecture

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

- Interactive diagram: https://gitdiagram.com/yakimka/picodi
- Repository: https://github.com/yakimka/picodi

## Overview

##### Project Type and Purpose
- Picodi is a Python library (not a standalone app) implementing Dependency Injection (DI).
- It provides decorators and a registry to manage lifecycles and scopes (singleton, request, etc.) in both sync and async code.
- It integrates with frameworks like FastAPI, Starlette, and pytest, and ships with docs, tests, CI pipelines, and benchmark data.

a. Source Code (“picodi/” folder)
- Core modules:
– _state.py: holds the global registry and storage for scoped instances.
– _scopes.py: defines scope classes (SingletonScope, NullScope, custom scopes).
– _inject_decorator.py & _internal.py: implement @inject decorator and plumbing.
– registry.py: API for registering providers, setting scopes, and lifecycle management (alifespan).
– helpers.py & support.py: utility functions (get_value, resolving logic).
- Types and interfaces: _types.py.
- Integrations:
– fastapi.py, starlette.py, _pytest.py, _pytest_asyncio.py under picodi/integrations.

- FastAPI / Starlette application
- pytest test suites (sync and async plugins)

c. Configuration & Tooling
- CI/CD: .github/workflows/workflow-ci.yml, ci.sh, Makefile (test, lint, build)
- Docker: Dockerfile-dev, docker-compose.yml
- Documentation: docs/ (Sphinx sources, tutorials, API reference)
- Benchmark data: .benchmarks/ (JSON results for different Python versions)

d. Tests (“tests/” folder)
- Core module tests
- Integration tests for frameworks
- Registry & lifecycle tests
- Scope behavior tests
- Benchmarks and race-condition tests

##### Relationships and Data Flows
- User Code invokes functions/classes decorated with @inject →
InjectDecorator (picodi/_inject_decorator.py) intercepts call →
Delegates to Registry (picodi/registry.py) to resolve dependencies →
Registry consults Scope Manager (picodi/_scopes.py) →
- For each dependency provider, checks/_state stores or initializes instance →
- Yields instances up the chain →
Decorator invokes original function with fully resolved args →
If async, coroutines are awaited; if sync, direct call.
- Lifecycle (alifespan) hooks into application startup/shutdown →
Pre-initializes providers marked auto_init →
Cleans up resources at shutdown.
- Integrations modules register framework-specific startup/shutdown hooks and injection points (FastAPI dependencies, pytest fixtures).

##### Architectural Patterns and Principles
- Inversion of Control via decorators and registry
- Scope management for lifecycles (Singleton, ContextVar-based, null, custom)
- Pluggable integration points (strategy pattern) for frameworks
- Zero external deps; pure-Python modular design
- Separation of concerns: core logic vs. integrations vs. docs vs. tests vs. CI

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Frameworks Layer
    subgraph "External Frameworks" 
        direction TB
        UserApp["User Application Code"]:::external
        FastAPI["FastAPI / Starlette App"]:::external
        Pytest["pytest Test Runner"]:::external
    end

    %% Integrations Layer
    subgraph "Picodi Integrations" 
        direction TB
        FastAPI_Int["FastAPI Integration"]:::integration
        Starlette_Int["Starlette Integration"]:::integration
        PytestSync_Int["pytest Integration"]:::integration
        PytestAsync_Int["pytest-asyncio Integration"]:::integration
    end

    %% Core Engine Layer
    subgraph "Core DI Engine" 
        direction TB
        subgraph "Core Modules"
            direction TB
            InjectDec["@inject Decorator"]:::core
            Registry["picodi.registry"]:::core
            Scopes["Scope Manager"]:::core
            State["Registry State Store"]:::core
            Helpers["Helper Functions"]:::core
            Support["Support Utilities"]:::core
            Types["Type Definitions"]:::core
            Internal["Internal Plumbing"]:::core
        end
    end

    %% Auxiliary Components
    subgraph "Auxiliary" 
        direction TB
        Docs["Documentation (Sphinx)"]:::aux
        Benchmarks["Benchmark Data"]:::aux
        CI["CI/CD & Scripts"]:::aux
        Docker["Docker Setup"]:::aux
        Tests["Test Suite"]:::aux
    end

    %% Data Flows
    UserApp -->|"invoke decorated function"| InjectDec
    FastAPI -->|"framework hooks"| FastAPI_Int
    FastAPI_Int -->|"registers hooks"| InjectDec
    Starlette -->|"framework hooks"| Starlette_Int
    Starlette_Int -->|"registers hooks"| InjectDec
    Pytest -->|"pytest fixtures"| PytestSync_Int
    PytestSync_Int -->|"registers fixtures"| InjectDec
    Pytest -->|"async fixtures"| PytestAsync_Int
    PytestAsync_Int -->|"registers fixtures"| InjectDec

    InjectDec -->|"delegates to"| Registry
    Registry -->|"resolve dependency"| Scopes
    Scopes -->|"get or create instance"| State
    Scopes -->|"invoke"| Helpers
    Helpers -->|"util logic"| Support
    Registry -->|"uses types"| Types
    InjectDec -->|"uses internal"| Internal
    State -->|"cache store"| State

    %% Side connections
    Docs -.->|auxiliary| Core
    Benchmarks -.->|auxiliary| Core
    CI -.->|auxiliary| Core
    Docker -.->|auxiliary| Core
    Tests -.->|auxiliary| Core

    %% Click Events
    click State "https://github.com/yakimka/picodi/blob/main/picodi/_state.py"
    click Scopes "https://github.com/yakimka/picodi/blob/main/picodi/_scopes.py"
    click InjectDec "https://github.com/yakimka/picodi/blob/main/picodi/_inject_decorator.py"
    click Internal "https://github.com/yakimka/picodi/blob/main/picodi/_internal.py"
    click Types "https://github.com/yakimka/picodi/blob/main/picodi/_types.py"
    click Helpers "https://github.com/yakimka/picodi/blob/main/picodi/helpers.py"
    click Support "https://github.com/yakimka/picodi/blob/main/picodi/support.py"
    click FastAPI_Int "https://github.com/yakimka/picodi/blob/main/picodi/integrations/fastapi.py"
    click Starlette_Int "https://github.com/yakimka/picodi/blob/main/picodi/integrations/starlette.py"
    click PytestSync_Int "https://github.com/yakimka/picodi/blob/main/picodi/integrations/_pytest.py"
    click PytestAsync_Int "https://github.com/yakimka/picodi/blob/main/picodi/integrations/_pytest_asyncio.py"
    click Docs "https://github.com/yakimka/picodi/tree/main/docs/"
    click Benchmarks "https://github.com/yakimka/picodi/tree/main/.benchmarks/"
    click CI "https://github.com/yakimka/picodi/blob/main/.github/workflows/workflow-ci.yml"
    click CI "https://github.com/yakimka/picodi/blob/main/ci.sh"
    click CI "https://github.com/yakimka/picodi/tree/main/Makefile"
    click Docker "https://github.com/yakimka/picodi/tree/main/Dockerfile-dev"
    click Docker "https://github.com/yakimka/picodi/blob/main/docker-compose.yml"
    click Tests "https://github.com/yakimka/picodi/tree/main/tests/"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#084b8a,stroke-width:1px
    classDef integration fill:#d9ead3,stroke:#274e13,stroke-width:1px
    classDef external fill:#fce5cd,stroke:#9c6500,stroke-width:1px
    classDef aux fill:#eeeeee,stroke:#666666,stroke-width:1px
    classDef cylinder shape: cylinder
```
