# rsalmei/alive-progress architecture

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

- Interactive diagram: https://gitdiagram.com/rsalmei/alive-progress
- Repository: https://github.com/rsalmei/alive-progress

## Overview

##### Project type and purpose
- alive-progress is an open-source Python library that provides richly animated, multithreaded progress bars and spinners.
- Its purpose is to let any Python program show progress, ETA, throughput, final receipts, print/log integration, and even a pause/resume mechanism—all via a simple API (`alive_bar`, `alive_it`).

##### File structure
Top-level:
- setup.py, requirements/, noxfile.py, justfile, CI config – the packaging, build, test, and CI pipeline.
- README.md, CHANGELOG.md, LICENSE – documentation and governance.
- docs/ – ancillary guides.
- img/ – demo images.
- tests/ – unit tests organized in parallel to source modules.
Core package (alive_progress/):
- animations/ – factories for spinners, bars, and the spinner compiler.
- core/ – calibration, configuration, hook manager (print/log hooks), and progress context.
- styles/ – predefined themes and “showtime” exhibits.
- tools/ – small executables (demo, repl, sampling).

##### README for additional insights
- Describes the high-level architecture: a configurable core that drives animations via closures and generators.
- Mentions the multithreaded update loop, exponential smoothing for ETA, and the cell architecture for Unicode.
- Lists extensibility points: custom animations, global or per-bar configuration, custom widgets.

a. Main components
1. User Application (any Python code)
2. Public API Layer (alive_bar, alive_it)
3. Configuration Handler (global and local config)
4. Core Progress Engine
– Calibration Service (FPS curve)
– Hook Manager (print/log intercept)
– Progress Context (state, counters, threads)
5. Animation Subsystem
– Spinner Compiler (pre-compiles frames and cycles)
– Spinner & Bar Factories (closures generating frame generators)
– Cell Architecture (grapheme cluster handling)
– Runner Thread(s) (asynchronous updates)
6. Output Adapters
– Terminal/TTY
– Jupyter Notebook
– File-like objects (stdout/stderr)
7. Tools and Utilities
– CLI demos (demo, repl)
– Sampling, unicode tests
8. External Dependencies
– about-time (timing tools)
– grapheme (Unicode cluster detection)
– Python stdlib (logging, threading, io)
b. Relationships and data flow
- User code → invokes API → passes through Configuration Handler → instantiates Progress Context.
- Progress Context spawns Runner Thread(s) → uses Calibration Service and state to schedule refresh.
- Each refresh tick queries Spinner & Bar Factories → feeds data to Spinner Compiler (once) → Runner Thread writes output via Output Adapters.
- Hook Manager intercepts print() and logging calls, enriching them with current progress → routes through same Output Adapters.
- Tools (demo/repl) sit atop the API layer, reusing core components.
c. Architectural patterns and principles
- Functional closures and generator-based factories for lightweight extensibility.
- Single responsibility: each subpackage (animations, core, utils) has a clear domain.
- Threaded update loop decoupled from user thread to minimize CPU usage.
- Strategy pattern via pluggable spinner/bar factories and themes.
- Observer-like hooks for print/log integration.
d. Key technologies/frameworks
- Python 3.6+ using threading, generators, closures.
- External packages: about-time, grapheme.
- CI: GitHub Actions, nox test automation.
- Packaging: setuptools, requirements files.

##### Final recommendations
- Be very detailed: include submodules like calibration, hook manager, cell utils.
- Multi-threaded behavior: mark the Runner Thread separate from the main user thread.
- Factory-compiler separation: show that factories produce generators, the compiler materializes frames once.
- Integration points: print/log hooks, Jupyter vs. TTY outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    UserApp["User Application"]:::green
    subgraph "Public API Layer"
        API["alive_bar, alive_it"]:::green
    end

    %% Configuration
    subgraph CoreEngine["Core Progress Engine"]
        Config["Configuration Handler"]:::blue
        ProgressContext["Progress Context"]:::blue
        Calibration["Calibration Service"]:::blue
        HookManager["Hook Manager"]:::blue
        RunnerThread["Runner Thread(s)"]:::blue
    end

    %% Animation Subsystem
    subgraph Animation["Animation Subsystem"]
        SpinnerFactory["Spinner Factory"]:::orange
        BarFactory["Bar Factory"]:::orange
        SpinnerCompiler["Spinner Compiler"]:::orange
        AnimUtils["Animation Utilities"]:::orange
    end

    %% Styles
    subgraph Styles["Styles/Themes"]
        Exhibit["Exhibit"]:::orange
        InternalStyle["Internal"]:::orange
    end

    %% Utils & I/O
    subgraph UtilsIO["Utils & I/O"]
        CellArch["Cell Architecture"]:::gray
        ColorUtils["Color Utilities"]:::gray
        TimingUtils["Timing Utilities"]:::gray
        subgraph TerminalAdapters
            TTY["Terminal Adapter (TTY)"]:::gray
            NonTTY["Terminal Adapter (Non-TTY)"]:::gray
            Jupyter["Terminal Adapter (Jupyter)"]:::gray
            Void["Void Adapter"]:::gray
        end
    end

    %% Tools
    subgraph Tools["CLI Tools"]
        Demo["Demo Tool"]:::green
        REPL["REPL Tool"]:::green
        Sampling["Sampling Tool"]:::green
        UnicodeBreaks["Unicode Breaks Tool"]:::green
        ToolsUtils["Tools Utilities"]:::gray
    end

    %% External Dependencies
    subgraph External["External Dependencies"]
        AboutTime["about-time"]:::red
        Grapheme["grapheme"]:::red
        StdLib["Python stdlib"]:::red
    end

    %% Connections
    UserApp -->|invokes| API
    API -->|uses| Config
    Config -->|initializes| ProgressContext
    ProgressContext -->|spawns| RunnerThread
    RunnerThread -->|calls| Calibration
    RunnerThread -->|uses| HookManager
    RunnerThread -->|requests frames| SpinnerFactory
    RunnerThread -->|requests frames| BarFactory
    SpinnerFactory -->|"generates frame generators"| SpinnerCompiler
    BarFactory -->|"generates frame generators"| SpinnerCompiler
    SpinnerCompiler -->|"compiles frames"| RunnerThread
    RunnerThread -->|renders| TTY
    RunnerThread -->|renders| NonTTY
    RunnerThread -->|renders| Jupyter
    RunnerThread -->|renders| Void
    HookManager -->|intercepts print/log| TTY
    HookManager -->|intercepts print/log| NonTTY
    HookManager -->|intercepts print/log| Jupyter
    Demo -->|uses| API
    REPL -->|uses| API
    Sampling -->|uses| API
    UnicodeBreaks -->|uses| API
    Demo -->|imports| ToolsUtils
    REPL -->|imports| ToolsUtils
    Sampling -->|imports| ToolsUtils
    UnicodeBreaks -->|imports| ToolsUtils

    %% External flows
    AboutTime -.->|wraps timing| TimingUtils
    Grapheme -.->|drives unicode| CellArch
    StdLib -.->|provides threading| RunnerThread
    StdLib -.->|provides logging| HookManager

    %% Click Events
    click API "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/__init__.py"
    click Config "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/core/configuration.py"
    click ProgressContext "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/core/progress.py"
    click Calibration "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/core/calibration.py"
    click HookManager "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/core/hook_manager.py"
    click SpinnerCompiler "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/animations/spinner_compiler.py"
    click SpinnerFactory "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/animations/spinners.py"
    click BarFactory "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/animations/bars.py"
    click AnimUtils "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/animations/utils.py"
    click Exhibit "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/styles/exhibit.py"
    click InternalStyle "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/styles/internal.py"
    click CellArch "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/utils/cells.py"
    click ColorUtils "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/utils/colors.py"
    click TimingUtils "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/utils/timing.py"
    click TTY "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/utils/terminal/tty.py"
    click NonTTY "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/utils/terminal/non_tty.py"
    click Jupyter "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/utils/terminal/jupyter.py"
    click Void "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/utils/terminal/void.py"
    click Demo "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/tools/demo.py"
    click REPL "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/tools/repl.py"
    click Sampling "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/tools/sampling.py"
    click UnicodeBreaks "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/tools/unicode_breaks.py"
    click ToolsUtils "https://github.com/rsalmei/alive-progress/blob/main/alive_progress/tools/utils.py"

    %% Styles
    classDef green fill:#e0f7e9,stroke:#2ecc71,color:#2ecc71;
    classDef blue fill:#e8f1f8,stroke:#3498db,color:#3498db;
    classDef orange fill:#fef3e0,stroke:#e67e22,color:#d35400;
    classDef gray fill:#f5f5f5,stroke:#7f8c8d,color:#7f8c8d;
    classDef red stroke-dasharray: 5 5,stroke:#e74c3c,color:#e74c3c;
```
