# brannondorsey/passgan architecture

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

- Interactive diagram: https://gitdiagram.com/brannondorsey/passgan
- Repository: https://github.com/brannondorsey/passgan

## Overview

##### Project Type and Purpose
- This is not a full-stack application in the classic sense but a research/ML project that offers both a training workflow and a sampling (inference) workflow.
- Its primary purpose is to train a GAN model on password datasets (e.g., RockYou) to eventually generate likely password samples.
- The README confirms two main user operations: training one’s own model (via train.py) and generating samples from a pretrained model (via sample.py).

##### Main Components (to include
a. Command Line Interface & Scripts:
- The entry points for operations are the CLI scripts “train.py” and “sample.py”.
- Additional helper scripts under the “bin” directory (e.g., prep-data.py, make-rockyou-full.py, randomize.py) support data preprocessing and preparation.

b. Data Management:
- “data” directory: Contains training data (or a placeholder for the data) that is used when training models.
- “pretrained” folder: Houses pretrained models, checkpoints, and ancillary files such as chmap and inv_charmap, which are used by the sampling process.

c. Core Model Components:
- “models.py” likely includes the architecture definitions of the GAN.
- “tflib” directory: Encapsulates various TensorFlow helper modules (e.g., operations for convolutions, batch normalization, layer normalization, etc.), as well as additional utilities like plotting and image saving modules. These collectively form the core of the deep learning infrastructure.

d. Utilities and Dependency Management:
- “utils.py”: Houses additional helper functions that might be used across training and sampling processes.
- “requirements.txt”: Specifies dependencies, indicating the underlying ML framework (TensorFlow), CUDA dependencies, and other required libraries.

##### System Interactions and Data Flow
- Data is ingested from the “data” directory (or preprocessed via “bin” scripts) into the training pipeline initiated by “train.py”.
- The training component uses “models.py” and several modules from “tflib” to build and train the GAN model.
- The training process saves intermediate checkpoints and final models into the “pretrained” directory.
- The “sample.py” component uses these pretrained model checkpoints to generate password samples.

##### Architectural Patterns and Design Principles
- There is a clear separation between “training” and “inference” stages.
- The project follows a modular design, where support libraries (tflib) are separated from the model definition (models.py) as well as the command-line interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% Data Preparation & Management
    subgraph "Data Preparation & Management"
        A1["data (Training Data)"]:::data
        A2["bin (Data Helper Scripts)"]:::scripts
        A3["requirements.txt (Dependencies)"]:::dependency
    end

    %% Model Training
    subgraph "Model Training"
        B1["train.py (Training Entry Point)"]:::cli
        B2["models.py (GAN Model Definition)"]:::core
        B3["tflib (TensorFlow Modules)"]:::core
        B4["utils.py (Helper Functions)"]:::core
    end

    %% Pretrained Artifacts
    subgraph "Pretrained Artifacts"
        C1["pretrained (Model Checkpoints)"]:::data
    end

    %% Model Sampling / Inference
    subgraph "Model Sampling / Inference"
        D1["sample.py (Sampling Entry Point)"]:::cli
    end

    %% External Dependencies
    subgraph "External Dependencies"
        E1["TensorFlow & CUDA"]:::external
    end

    %% Connections
    A1 -->|"inputTrainingData"| B1
    A2 -->|"dataPreprocessing"| B1
    A3 -->|"installsDependencies"| E1

    B1 -->|"trainsUsing"| B2
    B1 -->|"trainsUsing"| B3
    B1 -->|"uses"| B4
    B1 -.->|"requires"| E1

    B2 -->|"buildsModelUsing"| E1
    B3 -->|"implementsOps"| E1

    B1 -->|"savesCheckpoint"| C1
    C1 -->|"loadedBy"| D1
    B4 -->|"supports"| D1
    D1 -->|"loadsPretrainedModel"| C1

    %% Click Events
    click B1 "https://github.com/brannondorsey/passgan/blob/master//train.py"
    click D1 "https://github.com/brannondorsey/passgan/blob/master//sample.py"
    click A2 "https://github.com/brannondorsey/passgan/tree/master//bin"
    click A1 "https://github.com/brannondorsey/passgan/tree/master//data"
    click C1 "https://github.com/brannondorsey/passgan/tree/master//pretrained"
    click B2 "https://github.com/brannondorsey/passgan/blob/master//models.py"
    click B3 "https://github.com/brannondorsey/passgan/tree/master//tflib"
    click B4 "https://github.com/brannondorsey/passgan/blob/master//utils.py"
    click A3 "https://github.com/brannondorsey/passgan/blob/master//requirements.txt"

    %% Styles
    classDef cli fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef data fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef core fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef scripts fill:#F5DEB3,stroke:#000,stroke-width:2px;
    classDef dependency fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
