# explainingai-code/vqvae-pytorch architecture

> Architecture diagram of the GitHub repository explainingai-code/vqvae-pytorch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/explainingai-code/vqvae-pytorch
- Repository: https://github.com/explainingai-code/vqvae-pytorch

## Overview

This is a PyTorch VQ-VAE implementation for grayscale and colored MNIST, with an optional LSTM that models sequences of VQ-VAE codebook indices to generate digits. The main workflow trains the VQ-VAE, runs inference to produce reconstructions and saved encodings, trains the LSTM on those encodings, then samples indices and decodes them into images. The graph includes the documented minimal standalone VQ-VAE path. Relationships are limited to those visible in excerpts or explicitly described in the README; configuration files and data contents were not inspected.

Main entry points: [`tools/infer_vqvae.py`](https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/infer_vqvae.py) (Inference), [`tools/generate_images.py`](https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/generate_images.py) (Image Generation), [`model/vqvae.py`](https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/vqvae.py) (VQ-VAE Model), [`tools/train_vqvae.py`](https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/train_vqvae.py) (VQ-VAE Trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data"]
  node_config["Run Config"]
  node_mnist["MNIST Dataset<br/>[mnist_dataset.py]"]
end

subgraph group_vqvae["VQ-VAE"]
  node_train_vq["VQ-VAE Trainer<br/>[train_vqvae.py]"]
  node_encoder["Encoder<br/>[encoder.py]"]
  node_quantizer["Codebook Quantizer<br/>[quantizer.py]"]
  node_decoder["Decoder<br/>[decoder.py]"]
  node_vqvae_model["VQ-VAE Model<br/>[vqvae.py]"]
  node_simple["Simple VQ-VAE"]
  node_infer["Inference<br/>[infer_vqvae.py]"]
end

subgraph group_sequence["Sequence Generation"]
  node_lstm_train["LSTM Trainer<br/>[train_lstm.py]"]
  node_lstm_model["LSTM Model<br/>[train_lstm.py]"]
  node_generate["Image Generation<br/>[generate_images.py]"]
end

subgraph group_artifacts["Run Artifacts"]
  node_encoding_store["Code Encodings"]
  node_checkpoint["VQ-VAE Checkpoint"]
  node_lstm_checkpoint["LSTM Checkpoint"]
  node_images["Generated Images"]
  node_reconstructions["Reconstructions"]
end

node_user(("Engineer"))

node_user -->|"starts training"| node_train_vq
node_config -->|"configures"| node_train_vq
node_train_vq -->|"loads images"| node_mnist
node_train_vq -->|"trains"| node_vqvae_model
node_vqvae_model -->|"encodes"| node_encoder
node_vqvae_model -->|"quantizes"| node_quantizer
node_vqvae_model -->|"decodes"| node_decoder
node_train_vq -->|"saves weights"| node_checkpoint
node_user -->|"starts inference"| node_infer
node_config -->|"configures"| node_infer
node_infer -->|"runs model"| node_vqvae_model
node_infer -->|"loads images"| node_mnist
node_infer -->|"loads weights"| node_checkpoint
node_infer -->|"writes encodings"| node_encoding_store
node_infer -->|"saves"| node_reconstructions
node_user -->|"starts training"| node_lstm_train
node_config -->|"configures"| node_lstm_train
node_lstm_train -->|"loads encodings"| node_encoding_store
node_lstm_train -->|"trains"| node_lstm_model
node_lstm_train -->|"saves weights"| node_lstm_checkpoint
node_user -->|"starts generation"| node_generate
node_config -->|"configures"| node_generate
node_generate -->|"loads weights"| node_lstm_checkpoint
node_generate -->|"samples indices"| node_lstm_model
node_generate -->|"loads weights"| node_checkpoint
node_generate -->|"decodes indices"| node_vqvae_model
node_generate -->|"saves"| node_images
node_user -->|"runs demo"| node_simple
node_simple -->|"loads images"| node_mnist
node_simple -->|"saves"| node_reconstructions

click node_config "https://github.com/explainingai-code/vqvae-pytorch/tree/main/config"
click node_mnist "https://github.com/explainingai-code/vqvae-pytorch/blob/main/dataset/mnist_dataset.py"
click node_train_vq "https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/train_vqvae.py"
click node_encoder "https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/encoder.py"
click node_quantizer "https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/quantizer.py"
click node_decoder "https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/decoder.py"
click node_vqvae_model "https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/vqvae.py"
click node_simple "https://github.com/explainingai-code/vqvae-pytorch/blob/main/run_simple_vqvae.py"
click node_infer "https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/infer_vqvae.py"
click node_lstm_train "https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/train_lstm.py"
click node_lstm_model "https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/train_lstm.py"
click node_generate "https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/generate_images.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_mnist toneBlue
class node_train_vq,node_encoder,node_quantizer,node_decoder,node_vqvae_model,node_simple,node_infer toneAmber
class node_lstm_train,node_lstm_model,node_generate toneMint
class node_encoding_store,node_checkpoint,node_lstm_checkpoint,node_images,node_reconstructions toneRose
class node_user toneIndigo
```

## Components

### Data

- [Run Config](https://github.com/explainingai-code/vqvae-pytorch/tree/main/config): `config`
- [MNIST Dataset](https://github.com/explainingai-code/vqvae-pytorch/blob/main/dataset/mnist_dataset.py): `dataset/mnist_dataset.py`

### VQ-VAE

- [VQ-VAE Trainer](https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/train_vqvae.py): `tools/train_vqvae.py`
- [Encoder](https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/encoder.py): `model/encoder.py`
- [Codebook Quantizer](https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/quantizer.py): `model/quantizer.py`
- [Decoder](https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/decoder.py): `model/decoder.py`
- [VQ-VAE Model](https://github.com/explainingai-code/vqvae-pytorch/blob/main/model/vqvae.py): `model/vqvae.py`
- [Simple VQ-VAE](https://github.com/explainingai-code/vqvae-pytorch/blob/main/run_simple_vqvae.py): `run_simple_vqvae.py`
- [Inference](https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/infer_vqvae.py): `tools/infer_vqvae.py`

### Sequence Generation

- [LSTM Trainer](https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/train_lstm.py): `tools/train_lstm.py`
- [LSTM Model](https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/train_lstm.py): `tools/train_lstm.py`
- [Image Generation](https://github.com/explainingai-code/vqvae-pytorch/blob/main/tools/generate_images.py): `tools/generate_images.py`

### Run Artifacts

- **Code Encodings**
- **VQ-VAE Checkpoint**
- **LSTM Checkpoint**
- **Generated Images**
- **Reconstructions**

### Other components

- **Engineer**

## Connections

- Engineer → VQ-VAE Trainer: starts training (evidence: `README.md`)
- Run Config → VQ-VAE Trainer: configures (evidence: `tools/train_vqvae.py`)
- VQ-VAE Trainer → MNIST Dataset: loads images (evidence: `tools/train_vqvae.py`)
- VQ-VAE Trainer → VQ-VAE Model: trains (evidence: `tools/train_vqvae.py`)
- VQ-VAE Model → Encoder: encodes (evidence: `model/vqvae.py`)
- VQ-VAE Model → Codebook Quantizer: quantizes (evidence: `model/vqvae.py`)
- VQ-VAE Model → Decoder: decodes (evidence: `model/vqvae.py`)
- VQ-VAE Trainer → VQ-VAE Checkpoint: saves weights (evidence: `tools/train_vqvae.py`)
- Engineer → Inference: starts inference (evidence: `README.md`)
- Run Config → Inference: configures (evidence: `tools/infer_vqvae.py`)
- Inference → VQ-VAE Model: runs model (evidence: `tools/infer_vqvae.py`)
- Inference → MNIST Dataset: loads images (evidence: `tools/infer_vqvae.py`)
- Inference → VQ-VAE Checkpoint: loads weights (evidence: `tools/infer_vqvae.py`)
- Inference → Code Encodings: writes encodings (evidence: `tools/infer_vqvae.py`)
- Inference → Reconstructions: saves (evidence: `tools/infer_vqvae.py`)
- Engineer → LSTM Trainer: starts training (evidence: `README.md`)
- Run Config → LSTM Trainer: configures (evidence: `tools/train_lstm.py`)
- LSTM Trainer → Code Encodings: loads encodings (evidence: `tools/train_lstm.py`)
- LSTM Trainer → LSTM Model: trains (evidence: `tools/train_lstm.py`)
- LSTM Trainer → LSTM Checkpoint: saves weights (evidence: `tools/train_lstm.py`)
- Engineer → Image Generation: starts generation (evidence: `README.md`)
- Run Config → Image Generation: configures (evidence: `tools/generate_images.py`)
- Image Generation → LSTM Checkpoint: loads weights (evidence: `tools/generate_images.py`)
- Image Generation → LSTM Model: samples indices (evidence: `tools/generate_images.py`)
- Image Generation → VQ-VAE Checkpoint: loads weights (evidence: `tools/generate_images.py`)
- Image Generation → VQ-VAE Model: decodes indices (evidence: `tools/generate_images.py`)
- Image Generation → Generated Images: saves (evidence: `tools/generate_images.py`)
- Engineer → Simple VQ-VAE: runs demo (evidence: `README.md`)
- Simple VQ-VAE → MNIST Dataset: loads images (evidence: `run_simple_vqvae.py`)
- Simple VQ-VAE → Reconstructions: saves (evidence: `run_simple_vqvae.py`)
