# amirarsalan90/tabfairgan architecture

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

- Interactive diagram: https://gitdiagram.com/amirarsalan90/tabfairgan
- Repository: https://github.com/amirarsalan90/tabfairgan

## Overview

##### Project type and purpose
- TabFairGAN is a Python library/package for fair synthetic tabular data generation using a Wasserstein GAN.
- It’s neither a web app nor a full‐stack system: it’s an ML/data‐generation tool that users integrate into Python workflows.

##### File structure
- Top level:
- setup.py, requirements.txt, MANIFEST.in → packaging & dependencies
- adult/adult.csv → sample dataset
- notebook/usage.ipynb → demo & usage examples
- src/tabfairgan/ → core library code
- In src/tabfairgan:
- main.py → public API entry (TFG class, training & generation orchestration)
- modules.py → defines model components (Generator, Discriminator, fairness loss modules)
- utils.py → data preprocessing, CSV I/O, metric calculations

##### README for additional insights
- The library exposes a single class (TFG) that takes a DataFrame + optional fairness_config
- Two modes:
a. Unconstrained GAN training (only WGAN losses)
b. Fairness‐constrained training (additional fairness loss weighted by λ)
- Output: synthetic DataFrame of specified size

##### Main components
a. Data Input Layer
- Raw CSV (e.g., adult.csv) → pandas.DataFrame
b. Preprocessing Module (utils.py)
- Categorical/continuous encoding, normalization
c. GAN Architecture (modules.py)
- Generator
- Discriminator (Critic)
- Fairness Constraint Module (conditional/appended to loss when provided)
d. Training Orchestrator (main.py → TFG.train())
- Loop over epochs & batches
- Compute WGAN loss + optional fairness loss
- Optimizer steps for G and D
e. Synthetic Data Generator (main.py → TFG.generate_fake_df())
- Sample latent vectors, run through Generator, post‐process to DataFrame
f. User Interface
- Python API (import tabfairgan.TFG)
- Jupyter Notebook demo
g. Packaging & Deployment
- setup.py & PyPI distribution

##### Relationships & interactions
- Data flows: CSV → Preprocessing → Batches → GAN training → Synthetic samples → Post‐processing → Output DataFrame
- Fairness config toggles an extra loss branch in the Discriminator training loop
- The Notebook & CLI use the same API layer (TFG)

##### Architectural patterns & design principles
- Modular code split by responsibility: I/O (utils), model definition (modules), orchestration (main)
- Separation of concerns: training vs. data generation vs. fairness logic
- Dependency injection of fairness parameters into the training loop

##### Key technologies & libraries
- Python 3.x, PyTorch (implied by GAN usage & device='cuda')
- pandas for DataFrame operations
- numpy/scipy for numerical processing
- setuptools for packaging

##### Elements
- Clear component labels: “Data Loader”, “Preprocessor”, “Generator”, “Discriminator”, “Fairness Module”, “Trainer”, “Synthetic Data Output”
- Data → Preprocessor → Trainer
- Trainer → Model components (G & D)
- Fairness config → Trainer
- Trainer → Synthetic Data Generator → Output
- Blue for data components
- Green for model components
- Orange for configuration/fairness

##### Detailed capturing of essential architectural elements
- Don’t just show “GAN”: break it into Generator and Discriminator subcomponents
- Post‐processing in utils (e.g., decoding one‐hot back to raw feature values)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Integration Layer
    subgraph "User Integration"
        API["Python API Entrypoint"]:::api
        NOTE["Jupyter Notebook Demo"]:::demo
        PKG["Packaging & Deployment"]:::pkg
    end

    %% Documentation
    subgraph "Documentation"
        DOC["Project README"]:::doc
    end

    %% Data Layer
    subgraph "Data Input Layer"
        DataDir["Sample Dataset Directory"]:::data
        DataInput["Raw CSV (adult.csv)"]:::data
    end

    %% Preprocessing
    Preprocess["Preprocessing Module"]:::data

    %% Training Orchestrator
    Trainer["Training Orchestrator\nTFG.train()"]:::process

    %% GAN Architecture
    subgraph "GAN Architecture"
        G["Generator"]:::model
        D["Discriminator (Critic)"]:::model
        F["Fairness Module\n(optional)"]:::optional
    end

    %% Synthetic Data Generation
    SynthGen["Synthetic Data Generator\nTFG.generate_fake_df()"]:::process

    %% Output
    Output["Synthetic Data Output\n(DataFrame)"]:::data

    %% Configuration
    Config["Fairness Config\n(λ weight)"]:::config

    %% Relationships
    DOC -->|documents| API
    API -->|invokes| Trainer
    NOTE -->|uses API| Trainer
    PKG -.->|installs via PyPI| API

    DataDir --> DataInput
    DataInput --> Preprocess
    Preprocess --> Trainer
    Trainer --> G
    Trainer --> D
    Config --> Trainer
    Trainer --> SynthGen
    SynthGen --> Output

    %% Click Events
    click API "https://github.com/amirarsalan90/tabfairgan/blob/main/src/tabfairgan/__init__.py"
    click NOTE "https://github.com/amirarsalan90/tabfairgan/blob/main/notebook/usage.ipynb"
    click PKG "https://github.com/amirarsalan90/tabfairgan/blob/main/setup.py"
    click PKG "https://github.com/amirarsalan90/tabfairgan/blob/main/MANIFEST.in"
    click PKG "https://github.com/amirarsalan90/tabfairgan/blob/main/requirements.txt"
    click DOC "https://github.com/amirarsalan90/tabfairgan/blob/main/README.md"
    click DataDir "https://github.com/amirarsalan90/tabfairgan/tree/main/adult/"
    click DataInput "https://github.com/amirarsalan90/tabfairgan/blob/main/adult/adult.csv"
    click Preprocess "https://github.com/amirarsalan90/tabfairgan/blob/main/src/tabfairgan/utils.py"
    click G "https://github.com/amirarsalan90/tabfairgan/blob/main/src/tabfairgan/modules.py"
    click D "https://github.com/amirarsalan90/tabfairgan/blob/main/src/tabfairgan/modules.py"
    click F "https://github.com/amirarsalan90/tabfairgan/blob/main/src/tabfairgan/modules.py"
    click Trainer "https://github.com/amirarsalan90/tabfairgan/blob/main/src/tabfairgan/main.py"
    click SynthGen "https://github.com/amirarsalan90/tabfairgan/blob/main/src/tabfairgan/main.py"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef model fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef process fill:#FFF9C4,stroke:#F57F17,color:#F57F17;
    classDef config fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef optional stroke-dasharray: 5 5,fill:#FFEBEE,stroke:#B71C1C,color:#B71C1C;
    classDef api fill:#E1BEE7,stroke:#4A148C,color:#4A148C;
    classDef demo fill:#F0F4C3,stroke:#827717,color:#827717;
    classDef pkg fill:#CFD8DC,stroke:#263238,color:#263238;
    classDef doc fill:#D7CCC8,stroke:#4E342E,color:#4E342E;
```
