# python-effect/effect architecture

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

- Interactive diagram: https://gitdiagram.com/python-effect/effect
- Repository: https://github.com/python-effect/effect

## Overview

##### Project type and purpose
- This is an open-source Python library (“Effect”) that provides a purely functional abstraction for handling side-effects (IO, state, async) via Intents, Effects, Dispatchers and Performers.
- It is not a full-stack app but a framework/tool you import into your Python projects to isolate and test side-effects.

##### File structure
- Top-level packaging and config:
- setup.py, setup.cfg, dev-requirements.txt, Makefile, .travis.yml ─ packaging, CI, linting and test harness
- docs/source ─ Sphinx docs and API reference
- effect/ ─ core library modules and tests
- Within effect/:
- _base.py, _dispatcher.py, _intents.py, _utils.py, etc. ─ core engine
- do.py, fold.py, io.py, parallel_async.py, ref.py, retry.py, threads.py ─ built-in effect Intents and combinators
- testing.py, _test_utils.py ─ testing helpers
- test_*.py ─ unit tests for each subsystem

##### README for additional insights
- Core concepts: Intent (any object), Effect wrapper, Dispatcher → Performer mapping, sync_perform entry point
- Emphasizes separation of “what” (Intent) from “how” (Performer)
- Supports sync, parallel-async, testers, retries, references

##### Diagramming recommendations
- Use UML Component or C4 Container notation:

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Client["Client Code"]:::external

    %% Core Engine
    subgraph "Core Engine"
        Effect["Effect (effect/_base.py)"]:::core
        IntentReg["Intent Registry (effect/_intents.py)"]:::core
        Dispatcher["TypeDispatcher (effect/_dispatcher.py)"]:::core
        SyncEntry["sync_perform entry point (effect/_sync.py)"]:::core
    end

    %% Intents & Combinators
    subgraph "Intents & Combinators"
        IO["IO Intent (effect/io.py)"]:::intents
        Ref["Reference Intent (effect/ref.py)"]:::intents
        Threads["Thread-based Intent (effect/threads.py)"]:::intents
        PAIntent["Parallel-async Intent (effect/parallel_async.py)"]:::intents
        Do["Monadic sequencing (effect/do.py)"]:::intents
        Fold["Folding combinator (effect/fold.py)"]:::intents
        Retry["Retry combinator (effect/retry.py)"]:::intents
    end

    %% Performers
    subgraph "Performers"
        PerformerSync["sync_performer decorator & sync_perform logic (effect/_sync.py)"]:::performers
        PerformerPA["Parallel-async performers (effect/parallel_async.py)"]:::performers
        CustomPerf["Custom Performers (user-defined)"]:::performers
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        Continuation["Continuation support (effect/_continuation.py)"]:::utils
        Utils["Misc utilities (effect/_utils.py)"]:::utils
        TestingAPI["Testing API (effect/testing.py)"]:::utils
        TestUtils["Internal test utils (effect/_test_utils.py)"]:::utils
    end

    %% Test Suite
    Tests["Test Suite (effect/tests)"]:::tests

    %% Documentation
    Docs["Sphinx Docs (docs/source)"]:::docs

    %% CI & Packaging
    subgraph "CI & Packaging"
        Travis[".travis.yml"]:::ci
        SetupPy["setup.py"]:::ci
        SetupCfg["setup.cfg"]:::ci
        DevReq["dev-requirements.txt"]:::ci
        MakefileNode["Makefile"]:::ci
    end

    %% Main Data Flow
    Client -->|"constructs"| Effect
    Effect -->|"calls"| SyncEntry
    SyncEntry -->|"looks up"| Dispatcher
    Dispatcher -->|"executes intent"| PerformerSync
    Dispatcher -->|"executes intent"| PerformerPA
    Dispatcher -->|"executes intent"| CustomPerf
    PerformerSync -->|"returns result"| SyncEntry
    PerformerPA -->|"returns result"| SyncEntry
    SyncEntry -->|"returns final value"| Client

    %% Intents to Dispatcher
    IO -->|"intent type"| Dispatcher
    Ref -->|"intent type"| Dispatcher
    Threads -->|"intent type"| Dispatcher
    PAIntent -->|"intent type"| Dispatcher
    Do -->|"builds Effect"| Effect
    Fold -->|"builds Effect"| Effect
    Retry -->|"builds Effect"| Effect

    %% Dependencies
    Do -.-> Continuation
    Fold -.-> Continuation
    Retry -.-> Continuation
    PerformerPA -.-> Utils

    %% Auxiliary flows
    TestingAPI -->|used by| Tests
    TestUtils -->|supports| Tests
    Docs -->|documents| Effect

    %% Click Events
    click Effect "https://github.com/python-effect/effect/blob/master/effect/_base.py"
    click IntentReg "https://github.com/python-effect/effect/blob/master/effect/_intents.py"
    click Dispatcher "https://github.com/python-effect/effect/blob/master/effect/_dispatcher.py"
    click SyncEntry "https://github.com/python-effect/effect/blob/master/effect/_sync.py"
    click IO "https://github.com/python-effect/effect/blob/master/effect/io.py"
    click Ref "https://github.com/python-effect/effect/blob/master/effect/ref.py"
    click Threads "https://github.com/python-effect/effect/blob/master/effect/threads.py"
    click PAIntent "https://github.com/python-effect/effect/blob/master/effect/parallel_async.py"
    click Do "https://github.com/python-effect/effect/blob/master/effect/do.py"
    click Fold "https://github.com/python-effect/effect/blob/master/effect/fold.py"
    click Retry "https://github.com/python-effect/effect/blob/master/effect/retry.py"
    click PerformerSync "https://github.com/python-effect/effect/blob/master/effect/_sync.py"
    click PerformerPA "https://github.com/python-effect/effect/blob/master/effect/parallel_async.py"
    click Continuation "https://github.com/python-effect/effect/blob/master/effect/_continuation.py"
    click Utils "https://github.com/python-effect/effect/blob/master/effect/_utils.py"
    click TestingAPI "https://github.com/python-effect/effect/blob/master/effect/testing.py"
    click TestUtils "https://github.com/python-effect/effect/blob/master/effect/_test_utils.py"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef core fill:#bbf,stroke:#333,stroke-width:2px
    classDef intents fill:#bfb,stroke:#333,stroke-width:2px
    classDef performers fill:#ffb,stroke:#333,stroke-width:2px
    classDef utils fill:#fbf,stroke:#333,stroke-width:2px
    classDef tests fill:#fbb,stroke:#333,stroke-width:2px
    classDef docs fill:#aff,stroke:#333,stroke-width:2px
    classDef ci fill:#ffa,stroke:#333,stroke-width:2px
```
