# yeonghyeon/cvae-anomalydetection-pytorch architecture

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

- Interactive diagram: https://gitdiagram.com/yeonghyeon/cvae-anomalydetection-pytorch
- Repository: https://github.com/yeonghyeon/cvae-anomalydetection-pytorch

## Overview

##### Project Type and Purpose
- This is a standalone machine-learning experiment implementing Anomaly Detection with a Convolutional Variational Auto-Encoder (CVAE) in PyTorch.
- It trains on MNIST or Fashion-MNIST data, learning a low-dimensional latent representation and flagging outliers by reconstruction error.

##### File Structure Analysis
- Top‐level files:
- README.md (project description, results, architecture)
- run.py (CLI entry point to configure and launch training/evaluation)
- source/ directory:
- datamanager.py – data loading, preprocessing, batching (MNIST & Fashion-MNIST)
- neuralnet.py – defines the CVAE model (encoder, decoder, reparameterization)
- solver.py – training loop, loss (reconstruction + KL divergence), optimizer setup, model checkpointing, evaluation metrics (AUROC)

##### Key Components
a. Data Pipeline
- Raw Dataset (MNIST / Fashion-MNIST)
- DataManager module: preprocessing → batching → train/test split
b. Model
- CVAE Encoder: convolutional layers → μ, σ outputs
- Latent Sampling: reparameterization trick
- CVAE Decoder: transpose convolutions → reconstructed image
c. Solver / Training
- Loss Computation: reconstruction loss + KL divergence
- Optimizer (e.g., Adam)
- Epoch loop, backpropagation, weight updates
d. Evaluation & Visualization
- Reconstruction outputs, latent-space projections
- Histogram of reconstruction errors → anomaly thresholding → AUROC
- Figures module (Matplotlib)

##### Relationships and Data Flow
- Encoder → Latent Code → Decoder
- Decoder → Reconstruction → Loss
- Loss → Solver → Weight updates → Model
- After each epoch/model variant: feed test set → generate plots/histograms → compute AUROC

##### Architectural Patterns and Principles
- Modular separation: DataManager, Model, Solver, Run Script
- Single responsibility per module (loading, modeling, training, orchestrating)
- Pipeline pattern: sequential data flow from ingestion → transformation → output

##### Relevant Technologies and Libraries
- PyTorch (torch, torch.nn, torch.optim)
- NumPy for array ops
- Matplotlib for visualizations
- Scikit-learn for AUROC metric
- Python 3.7 runtime

##### Final Advice
- Hyperparameters (latent dim, batch size) and metrics (AUROC).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration
    Run["run.py (CLI Entry Point)"]:::training
    click Run "https://github.com/yeonghyeon/cvae-anomalydetection-pytorch/blob/master/run.py"
    
    %% Data Pipeline
    subgraph "Data Pipeline"
        style DataManager fill:#cce5ff
        DataManager["DataManager\n(preprocessing, batching,\ntrain/test split)"]:::data
        click DataManager "https://github.com/yeonghyeon/cvae-anomalydetection-pytorch/blob/master/source/datamanager.py"
        RawData["Raw Dataset\n(MNIST / Fashion-MNIST)"]:::data
    end

    %% Model Internals
    subgraph "CVAE Model" 
        style Encoder fill:#d4edda
        Encoder["Encoder\n(convolutions → μ,σ)"]:::model
        style Sampling fill:#d4edda
        Sampling["Latent Sampling\n(reparameterization)"]:::model
        style Decoder fill:#d4edda
        Decoder["Decoder\n(transpose conv → reconstruction)"]:::model
        click Encoder "https://github.com/yeonghyeon/cvae-anomalydetection-pytorch/blob/master/source/neuralnet.py"
        click Sampling "https://github.com/yeonghyeon/cvae-anomalydetection-pytorch/blob/master/source/neuralnet.py"
        click Decoder "https://github.com/yeonghyeon/cvae-anomalydetection-pytorch/blob/master/source/neuralnet.py"
    end

    %% Training & Solver
    subgraph "Training Loop & Solver"
        style Solver fill:#ffe5b4
        Solver["Solver\n(loss comp, optimizer,\ncheckpoints, metrics)"]:::training
        click Solver "https://github.com/yeonghyeon/cvae-anomalydetection-pytorch/blob/master/source/solver.py"
    end

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        style Viz fill:#e2e3e5
        Viz["Figures & Plots\n(histograms, reconstructions,\nlatent projections)"]:::external
        click Viz "https://github.com/yeonghyeon/cvae-anomalydetection-pytorch/tree/master/figures/"
        README["README.md\n(overview, results,\ndiagrams)"]:::external
        click README "https://github.com/yeonghyeon/cvae-anomalydetection-pytorch/blob/master/README.md"
    end

    %% Data Flow
    RawData -->|"load images"| DataManager
    DataManager -->|"batches"| Encoder
    Encoder -->|"latent μ,σ"| Sampling
    Sampling -->|"sample z"| Decoder
    Decoder -->|"reconstructed images"| Solver
    Solver -->|"compute loss\n(recon + KL)"| Solver
    Solver -->|"update weights"| Decoder
    Solver -->|"update weights"| Encoder

    %% Control Flow
    Run -.->|invokes| Solver
    Run -.->|sets config| DataManager

    %% Evaluation Flow
    DataManager -->|"test batches"| Decoder
    Decoder -->|"reconstructed test"| Viz
    Solver -->|"compute AUROC"| Viz
    Viz -->|"include in"| README

    %% Legend
    subgraph "Legend"
        D["Data Components"]:::data
        M["Model Components"]:::model
        T["Training Components"]:::training
        E["External/Outputs"]:::external
    end

    classDef data fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef model fill:#d4edda,stroke:#333,stroke-width:1px
    classDef training fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
```
