# redgriff/t-vae-gan architecture

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

- Interactive diagram: https://gitdiagram.com/redgriff/t-vae-gan
- Repository: https://github.com/redgriff/t-vae-gan

## Overview

##### Project type and purpose
- Project type: A Python library for tabular data synthesis using a hybrid “t-Variational Autoencoder + GAN” model.
- Purpose: Load real tabular data, train a TVAeGAN model (encoder, decoder, critic), then generate synthetic data with similar distributions.

##### File structure
- Top-level:
- examples/ → sample data and example usage (adult.csv, example.ipynb, example.py)
- src/ → core Python modules
- requirements.txt → external dependencies (likely PyTorch, NumPy, pandas, etc.)
- README.md → project title; assumes more details are in code/docs.
- src/ modules:
- data_loader.py → ingest raw CSV or DataFrame
- data_handler.py → preprocess (normalization, categorical encoding, train/test split)
- encoder_critic.py → critic network (GAN discriminator)
- decoder_generator.py → generator network (GAN generator / VAE decoder)
- mlp_network.py → helper MLP blocks used by encoder/decoder/critic
- tvaegan_network.py → stitches encoder, decoder, critic into a single model class
- tvaegan_synthesizer.py → high-level API: trains the network, manages epochs, loss functions, and sampling

##### README for additional insights
- The README is minimal; the source code names reveal the architecture: a two-stage model (VAE pretraining + adversarial training) whose components are modularized in separate files.

a. Main components
- Data Ingestion Layer
– examples/adult.csv or user-provided CSV
– data_loader.py
- Data Preprocessing Layer
– data_handler.py (scalers, encoders)
- Model Definition
– mlp_network.py (shared building blocks)
– encoder_critic.py
– decoder_generator.py
– tvaegan_network.py
- Training Orchestrator
– tvaegan_synthesizer.py (trains VAE phase, then GAN phase)
- External Dependencies
– PyTorch/TensorFlow, NumPy, pandas
- Output
– Synthetic dataset (pandas DataFrame or CSV)

b. Relationships and interactions
- Raw Data → Data Loader → Data Handler → preprocessed tensors
- Preprocessed tensors → TVAeGAN Synthesizer
- Synthesizer pulls in TVAeGAN Network
- TVAeGAN Network uses MLP blocks to build Encoder, Decoder, Critic
- Training loop in Synthesizer:
– VAE pretraining: Encoder ↔ Decoder (reconstruction loss + KL)
– GAN training: Generator(Decoder) ↔ Critic (adversarial loss)
- After training: Synthesizer calls sampling API on TVAeGAN Network → outputs synthetic data → passes back through inverse transforms in Data Handler → final CSV/DataFrame

c. Architectural patterns and design principles
- Modularization: each network component in its own module
- Layered design: clear separation between data handling, model definition, and orchestration
- Reuse: MLP blocks factored into mlp_network.py
- Two-phase training pipeline encapsulated in synthesizer

d. Key technologies & libraries
- PyTorch (torch.nn, torch.optim)
- pandas / NumPy for data I/O and processing
- Scikit-learn utilities (scalers, encoders)

##### Elements
- Raw CSV → DataLoader → DataHandler → Synthesizer → TVAeGAN Network → Loss & Optimizers → back to Synthesizer
- Synthesizer → Sampling → DataHandler (inverse preprocess) → Synthetic CSV
- Blue for data layers (Loader/Handler)
- Green for model definition (Encoder, Decoder, Critic, MLP)
- Orange for orchestrator (Synthesizer)
- Gray for external dependencies
- Rectangles for code modules/classes
- Parallelograms for inputs/outputs

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Data Layers
  subgraph "Data Layers"
    RawCSV[(examples/adult.csv)]:::data
    DL["data_loader.py"]:::data
    DH["data_handler.py"]:::data
  end

  %% Model Definition
  subgraph "Model Definition"
    MLP["mlp_network.py"]:::model
    Critic["encoder_critic.py"]:::model
    Decoder["decoder_generator.py"]:::model
    Composite["tvaegan_network.py"]:::model
  end

  %% Orchestrator
  subgraph "Training Orchestrator"
    Synth["tvaegan_synthesizer.py"]:::orchestrator
  end

  %% External Dependencies
  subgraph "External Dependencies"
    Req["requirements.txt"]:::external
    READ["README.md"]:::external
  end

  %% Examples
  subgraph "Examples"
    ExPy["example.py"]:::data
    ExNB["example.ipynb"]:::data
  end

  %% Data Flow
  RawCSV -->|"raw data"| DL
  DL -->|"DataFrame"| DH
  DH -->|"preprocessed tensor batch"| Synth
  Synth -->|"VAE pretraining"| Composite
  Composite -->|"reconstruction loss + KL"| Synth
  Synth -->|"GAN training"| Composite
  Composite -->|"adversarial loss"| Synth
  Synth -->|"sampling API"| Composite
  Composite -->|"synthetic tensor batch"| Synth
  Synth -->|"synthetic samples"| DH
  DH -->|"inverse transform"| OutputCSV[(Synthetic CSV/DataFrame)]:::data

  %% Model Composition Links
  MLP --> Composite
  Critic --> Composite
  Decoder --> Composite

  %% Click Events
  click RawCSV "https://github.com/redgriff/t-vae-gan/blob/main/examples/adult.csv"
  click DL "https://github.com/redgriff/t-vae-gan/blob/main/src/data_loader.py"
  click DH "https://github.com/redgriff/t-vae-gan/blob/main/src/data_handler.py"
  click MLP "https://github.com/redgriff/t-vae-gan/blob/main/src/mlp_network.py"
  click Critic "https://github.com/redgriff/t-vae-gan/blob/main/src/encoder_critic.py"
  click Decoder "https://github.com/redgriff/t-vae-gan/blob/main/src/decoder_generator.py"
  click Composite "https://github.com/redgriff/t-vae-gan/blob/main/src/tvaegan_network.py"
  click Synth "https://github.com/redgriff/t-vae-gan/blob/main/src/tvaegan_synthesizer.py"
  click ExPy "https://github.com/redgriff/t-vae-gan/blob/main/examples/example.py"
  click ExNB "https://github.com/redgriff/t-vae-gan/blob/main/examples/example.ipynb"
  click Req "https://github.com/redgriff/t-vae-gan/blob/main/requirements.txt"
  click READ "https://github.com/redgriff/t-vae-gan/blob/main/README.md"

  %% Styles
  classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef model fill:#90EE90,stroke:#333,stroke-width:1px
  classDef orchestrator fill:#FFA500,stroke:#333,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
