# igf-psd/bozio_wasmer_simulations architecture

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

- Interactive diagram: https://gitdiagram.com/igf-psd/bozio_wasmer_simulations
- Repository: https://github.com/igf-psd/bozio_wasmer_simulations

## Overview

##### Project type and purpose
- This is a Python simulation library (bozio_wasmer_simulations) designed to quantify employer‐contribution reforms from the “Bozio-Wasmer” report.
- It includes empirical and theoretical simulators, data loaders, parameter files, scripts for batch runs, Jupyter notebooks for analysis, and MkDocs‐based documentation.

##### File structure
- Top‐level folders:
- bozio_wasmer_simulations/      ← Core Python package
– datasets/                    ← Data‐loading modules (base classes & XLS loaders)
– description/                 ← DescriptionBuilder abstractions
– simulation/                  ← Two subpackages: empirical/ & theoretical/
– utils/                       ← Shared utilities (passage, misc helpers)
- data/                          ← Raw XLS files (ZRR, ZRD, distributions)
- parameters/                    ← JSON files for default simulation parameters
- scripts/                       ← simulate.py entry point (reads config.yaml)
- notebooks/                     ← Example analysis notebooks
- outputs/ & logs/               ← Results and logging outputs
- docs/                          ← MkDocs source (API and conceptual docs)
- config.yaml                    ← Scenario definitions for scripts
- pyproject.toml, requirements.txt, mkdocs.yml

##### Extract insights from README
- Two simulation modes: empirical (budget & employment effects) and theoretical (wage‐increase incentives, PPV impact).
- Typical usage: instantiate a simulator class (e.g., CaptationMarginaleSimulator), call simulate_reform(...) with parameters and receive a DataFrame.
- Scripts orchestrate multiple reforms defined in config.yaml.
- Documentation generated via MkDocs.

##### Main components & relationships (
a. Data Inputs
- Raw data folder (Excel files)
- parameters/*.json
- config.yaml
b. Core Package (“bozio_wasmer_simulations”)
1. datasets loaders ← read raw data + parameters
2. description builder ← assemble metadata & scenario descriptions
3. simulation engines
- empirical simulator pipeline: preprocessing → weighting → reform application
- theoretical simulator pipeline: marginal capture rates (ppv, taux…)
4. utils ← shared functions (data passage, general helpers)
c. Orchestration & I/O
- scripts/simulate.py ← reads config.yaml, instantiates simulators, writes outputs to outputs/ & logs/
- notebooks ← consume core package APIs for ad‐hoc analysis
d. Documentation
- docs/ (MkDocs) ← auto‐generated API docs & conceptual pages

Data Inputs → Dataset Loaders → Description Builder → Simulation Engines → Outputs/Logs
Scripts orchestrate the pipeline; Notebooks and user code call the same API.

##### Architectural patterns & principles
- Modular package with clear separation: data‐ingestion, description, simulation logic, utilities.
- Single Responsibility: each subpackage addresses one concern.
- Plugin‐style extensibility: new simulation types can be added under simulation/.
- Configuration‐driven runs: script driven by config.yaml to run multiple scenarios in batch.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    RawData["Raw Data Inputs (Excel files)"]:::data
    ParamFiles["Parameter Files (JSON)"]:::data
    ConfigYAML["Configuration Definitions (config.yaml)"]:::data

    %% Core Package
    subgraph "Core Package: bozio_wasmer_simulations"
        direction TB
        Datasets["Dataset Loaders"]:::core
        Description["Description Builder"]:::core
        subgraph "Simulation Engines"
            direction TB
            Empirical["Empirical Simulation Engine"]:::core
            Theoretical["Theoretical Simulation Engine"]:::core
        end
        Utils["Shared Utilities"]:::core
    end

    %% Orchestrators
    subgraph "Orchestration & Analysis"
        direction TB
        Script["Batch Orchestration Script"]:::orchestrator
        Notebooks["Interactive Notebooks"]:::orchestrator
    end

    %% Outputs
    Outputs["Outputs Directory"]:::output
    Logs["Logs Directory"]:::output

    %% Documentation
    Docs["Documentation (MkDocs)"]:::docs
    PyConfig["Project Config Files"]:::docs

    %% Data Flow
    RawData -->|"reads from"| Datasets
    ParamFiles -->|"reads from"| Datasets
    Datasets -->|"provides data"| Description
    Description -->|"metadata & scenarios"| Empirical
    Description -->|"metadata & scenarios"| Theoretical
    Utils --> Empirical
    Utils --> Theoretical
    Empirical -->|"simulation results"| Outputs
    Empirical -->|"logs"| Logs
    Theoretical -->|"simulation results"| Outputs
    Theoretical -->|"logs"| Logs

    %% Orchestration
    ConfigYAML -->|"config input"| Script
    Script -->|"calls API"| Datasets
    Script -->|"calls API"| Description
    Script -->|"calls API"| Empirical
    Script -->|"calls API"| Theoretical
    Script --> Outputs
    Script --> Logs

    Notebooks -->|"calls API"| Description
    Notebooks -->|"calls API"| Empirical
    Notebooks -->|"calls API"| Theoretical

    %% Documentation Flow
    Docs -->|"built via mkdocs.yml"| Docs
    PyConfig --> Docs

    %% Click Events
    click RawData "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/data/"
    click ParamFiles "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/parameters/"
    click ConfigYAML "https://github.com/igf-psd/bozio_wasmer_simulations/blob/main/config.yaml"
    click Datasets "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/bozio_wasmer_simulations/datasets/"
    click Description "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/bozio_wasmer_simulations/description/"
    click Empirical "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/bozio_wasmer_simulations/simulation/empirical/"
    click Theoretical "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/bozio_wasmer_simulations/simulation/theoretical/"
    click Utils "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/bozio_wasmer_simulations/utils/"
    click Script "https://github.com/igf-psd/bozio_wasmer_simulations/blob/main/scripts/simulate.py"
    click Notebooks "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/notebooks/"
    click Outputs "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/outputs/"
    click Logs "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/logs/"
    click Docs "https://github.com/igf-psd/bozio_wasmer_simulations/tree/main/docs/"
    click PyConfig "https://github.com/igf-psd/bozio_wasmer_simulations/blob/main/pyproject.toml"

    %% Styles
    classDef data fill:#9f6,stroke:#393;
    classDef core fill:#6cf,stroke:#036;
    classDef orchestrator fill:#c6f,stroke:#630;
    classDef output fill:#fa6,stroke:#a50;
    classDef docs fill:#ccc,stroke:#666;
```
