# alti3/stateless-py architecture

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

- Interactive diagram: https://gitdiagram.com/alti3/stateless-py
- Repository: https://github.com/alti3/stateless-py

## Overview

The “stateless‐py” project is a Python library that implements a state machine framework inspired by the C# Stateless library. Its purpose is to allow developers to fluently configure and use state machines featuring capabilities such as guards, actions, asynchronous transitions, hierarchical states, and even graph visualizations.

##### Project Type and Purpose
- This is not a full-stack application but rather a standalone, extensible library that manages state machines.
- Its primary goal is to let users define states, triggers, transitions, and actions (including async ones) in a fluent and declarative style. The README highlights usage examples—such as on/off switches, bug tracker, asynchronous actions, and complex state hierarchies—indicating the diverse scenarios that the library supports.

##### File Structure
- Key Directories:
- actions.py – for handling state entry/exit actions.
- firing_modes.py – likely managing different ways transitions can be triggered.
- state_machine.py – encapsulating the logic behind state transitions.
- Other modules (guards, transitions, exceptions, introspection via reflection, etc.) clearly separate concerns within the engine.
– The “examples” directory provides scripts showing how to use the library, which indirectly demonstrates the interactions of the major components.
– The “tests” directory contains unit tests ensuring each module/component behaves correctly.
- Additional Files:
– Configuration and CI/CD (e.g., .github/workflows), and pyproject.toml indicate modern project practices and dependency management.

##### Extracting Architectural Insights from the README
- The README details the extensive feature list—fluent API, parameterized triggers, async support, introspection via Pydantic models, and graph generation—which underscore the modularity of the system.
- It outlines multiple usage scenarios, which can be represented by showing various state flows and how the state machine manages both synchronous and asynchronous transitions.

a. Main Components to Include:
- Core State Machine Engine: Central module managing states and triggers (src/stateless/state_machine.py).
- Configuration & Transition Modules: Components for setting up transitions (actions, guards, transition logic in modules like actions.py, guards.py, transition.py).
- Async Processing Unit: Part of the engine that supports asynchronous operations (referenced in tests like test_async.py).
- Introspection/Reflection: The component that, using reflection (src/stateless/reflection.py) and Pydantic models, exposes the machine’s internal structure.
- Error Handling: Exception management from exceptions.py and transitional error checks.

b. Relationships and Interactions:
- The State Machine Engine serves as the central hub where state transitions and trigger firings are processed.
- Configuration modules receive fluent API calls (e.g., configure, permit) that define the operational rules; these rules are then utilized by the engine during runtime.
- When a trigger is fired, the engine consults the transition module to determine if a state change is valid, taking into account guards and actions.
- The guard modules determine if transitions are allowed, while action modules execute entry/exit behaviors.
- Graph generation and introspection modules tap into the state machine’s configuration to provide a visual overview or detailed model of the state structure.
- Asynchronous capabilities (fire_async) are a separate path where the engine interfaces with Python’s async event loop to execute tasks without blocking.

c. Architectural Patterns and Design Principles:
- Fluent Interface / Builder Pattern: The API design (e.g., sm.configure(...).permit(...)) is a clear example of this.
- Separation of Concerns: Distinct modules for actions, transitions, introspection, and visualization ensure that each component has a single responsibility.
- Modular Design: The project cleanly separates the core engine from example usage and testing, which aids in maintenance and future extensions.
- Optional Asynchrony: Support for async guards and actions demonstrates design for modern, non-blocking operations.

d. Relevant Technologies and Frameworks:
- Language: Python (using enums, asyncio, and type hinting).
- Libraries: Pydantic (for generating introspection models), Graphviz (for DOT graph creation), and GitHub Actions for CI/CD.
- Testing: Pytest framework as indicated by the “tests” directory.

##### Elements
- Clear labels for each component (e.g., “State Machine Engine”, “Transition Manager”, “Action Executor”, “Async Handler”, “Graph Generator”).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Configuration and Transition Modules"
        CFG["State Configuration"]:::config
        TRANS["Transition Manager"]:::config
    end

    subgraph "Core Engine"
        CORE["State Machine Engine"]:::core
    end

    subgraph "Processing Components"
        ACT["Action Executor"]:::processing
        FIRE["Firing Modes"]:::processing
        GUARD["Guard Evaluation"]:::processing
    end

    subgraph "Visualization & Introspection"
        GRAPH["Graph Generator"]:::viz
        INTROSPECT["Introspection & Reflection"]:::viz
    end

    ERROR["Error Handling"]:::error

    CFG --> CORE
    TRANS --> CORE
    CORE --> ACT
    CORE --> FIRE
    CORE --> GUARD
    CORE --> GRAPH
    CORE --> INTROSPECT
    CORE --> ERROR
    GUARD --> ERROR

    click CORE "https://github.com/alti3/stateless-py/blob/main/src/stateless/state_machine.py"
    click CFG "https://github.com/alti3/stateless-py/blob/main/src/stateless/state_configuration.py"
    click TRANS "https://github.com/alti3/stateless-py/blob/main/src/stateless/transition.py"
    click ACT "https://github.com/alti3/stateless-py/blob/main/src/stateless/actions.py"
    click FIRE "https://github.com/alti3/stateless-py/blob/main/src/stateless/firing_modes.py"
    click GUARD "https://github.com/alti3/stateless-py/blob/main/src/stateless/guards.py"
    click GRAPH "https://github.com/alti3/stateless-py/blob/main/src/stateless/graph.py"
    click INTROSPECT "https://github.com/alti3/stateless-py/blob/main/src/stateless/reflection.py"
    click ERROR "https://github.com/alti3/stateless-py/blob/main/src/stateless/exceptions.py"

    classDef config fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef processing fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef viz fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef error fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
