# rblasser/logical-rush architecture

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

- Interactive diagram: https://gitdiagram.com/rblasser/logical-rush
- Repository: https://github.com/rblasser/logical-rush

## Overview

##### Project type and purpose
- This is a Python batch-computing library (“logical_rush”) for loan amortization and cashflow generation.
- It is distributed as a single package with functions for sequential, parallel, and GIL-released computation of cashflows.
- Typical usage: data preparation via pandas, conversion to list-of-dict records, then feeding into the library’s APIs.

##### File structure
- Top level:
- LICENSE, README.md, setup.py
- logical_rush/ (Python package)
– __init__.py (exports cashflower_fn, cashflower_par, cashflower_gil)
– __pycache__/ (compiled bytecode)
- No distinct “frontend” or “backend”; it is a pure library.
- No external microservices or web servers, but it integrates with pandas and the Python runtime.
- Packaging configuration in setup.py suggests it’s intended for pip distribution.

##### README for additional insights
- Core workflow:
a. User script creates a pandas.DataFrame of loan parameters.
b. Converts DataFrame to list-of-dicts (“dx_dict”).
c. Calls one of three entry points:
– cashflower_fn   (sequential Python loop)
– cashflower_par  (parallel via multiprocessing)
– cashflower_gil  (GIL-released compute code)
d. Library returns a list of cashflow records for each loan.
- Benchmark script also writes CSV output.

##### Detail level
- Include:
- Entry point functions (cashflower_fn, cashflower_par, cashflower_gil)
- Data conversion step
- Worker processes in the parallel path
- GIL release boundary in the GIL engine
- Avoid over-fragmentation; group internal helper functions under each engine unless they represent distinct modules.

## Diagram (Mermaid)

```mermaid
graph TB
    %% User Application Components
    UserApp["User Script / Data Prep"]:::user
    Pandas["pandas"]:::external
    RecordConv["Record Conversion<br/>(DataFrame → List[Dict])"]:::user

    %% Library Package and Compute Engines
    LR_pkg["logical_rush Library"]:::lib
    SeqEng["cashflower_fn<br/>(Sequential Engine)"]:::lib
    ParEng["cashflower_par<br/>(Parallel Engine)"]:::lib
    GILEng["cashflower_gil<br/>(GIL-Release Engine)"]:::lib

    %% External Dependencies
    MP["multiprocessing"]:::external
    PythonRT["Python Runtime"]:::external

    %% Output Sink
    Results["List[Dict] of Cashflow Records"]:::output
    CSV["CSV Output"]:::output

    %% Project Files & Docs
    Readme["README.md"]:::meta
    License["LICENSE"]:::meta
    Setup["setup.py"]:::meta

    %% Data Flow
    UserApp -->|uses| Pandas
    Pandas -->|provides DataFrame| RecordConv
    RecordConv -->|feeds data| LR_pkg
    LR_pkg --> SeqEng
    LR_pkg --> ParEng
    LR_pkg --> GILEng
    SeqEng --> Results
    ParEng --> Results
    GILEng --> Results
    Results -->|written via pandas| CSV

    %% Parallel and GIL interactions
    ParEng -->|fork processes| MP
    GILEng -->|"releases GIL"| PythonRT

    %% Project Files
    Readme
    License
    Setup

    %% Click Events
    click LR_pkg "https://github.com/rblasser/logical-rush/tree/main/logical_rush/"
    click SeqEng "https://github.com/rblasser/logical-rush/blob/main/logical_rush/__init__.py"
    click ParEng "https://github.com/rblasser/logical-rush/blob/main/logical_rush/__init__.py"
    click GILEng "https://github.com/rblasser/logical-rush/blob/main/logical_rush/__init__.py"
    click Readme "https://github.com/rblasser/logical-rush/blob/main/README.md"
    click License "https://github.com/rblasser/logical-rush/tree/main/LICENSE"
    click Setup "https://github.com/rblasser/logical-rush/blob/main/setup.py"

    %% Styles
    classDef user fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef lib fill:#DFFFE0,stroke:#228B22,stroke-width:1px;
    classDef external fill:#FFE4B5,stroke:#CD853F,stroke-width:1px;
    classDef output fill:#F0F0F0,stroke:#808080,stroke-width:1px;
    classDef meta fill:#FFF5E1,stroke:#DAA520,stroke-width:1px;
```
