# lemonmindyes/minidream architecture

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

- Interactive diagram: https://gitdiagram.com/lemonmindyes/minidream
- Repository: https://github.com/lemonmindyes/minidream

## Overview

##### Project Type and Purpose
- MiniDream is a PyTorch‐based research toolkit rather than a client/server or web app.
- It implements “mini” variants of several state‐of‐the‐art models (BPE tokenizer, MobileNet, ResNet, U-Net, ViT, VQ-VAE).
- Each model lives in its own top‐level Python package and can be trained via one of the train_*.py scripts.

##### File Structure Analysis
- Top-level artifacts:
- modules: mini_bpe/, mini_mobilenet/, mini_resnet/, mini_unet/, mini_vit/, mini_vqvae/
- train scripts: train_mini_*.py
- requirements.txt, README.md, imgs/
- Each module contains:
- config.py — hyperparameter container
- model definition(s) (.py)
- utils.py or dataset.py where needed
- No server or database; dependencies are PyTorch and Lightning.

##### Insights from README
- Describes each model’s usage snippet and points to corresponding image in imgs/.
- Installation and training commands emphasize a CLI‐driven workflow.
- No external services; purely code modules and training pipelines.

a. Main Components
1. Model Modules (six packages)
- mini_bpe
- mini_mobilenet
- mini_resnet
- mini_unet
- mini_vit
- mini_vqvae
2. Training Controllers (train_mini_*.py scripts)
3. Shared Libraries
- PyTorch
- PyTorch Lightning
4. Auxiliary Artifacts
- Config objects (per‐model)
- Utils / dataset code
- Image assets (imgs/)
b. Relationships & Interactions
- Each train script:
- Imports Config and Model class from its module
- Instantiates Config → Model → Lightning Trainer → runs training
- Models call their own utils (e.g., tokenization, data transforms, visualization).
- Underlying ML framework (PyTorch, Lightning) provides tensor ops, training loop, checkpointing.
c. Architectural Patterns & Principles
- Package‐per‐model for modularity and extensibility.
- Config‐driven instantiation: separates hyperparameters from code.
- CLI entry points (train scripts) decouple experiments from module code.
d. Key Technologies
- Python packages (PEP 420)
- PyTorch as core DL library
- PyTorch Lightning for standardized training loops
- Standard Python utils for data loading/visualization

##### Detailed Capturing of Architectural Elements
- If desired, group the six model packages into a “Model Library” container.
- Directional flow:
1. User ▶ train_mini_resnet.py
2. ▶ Config (n_layers, num_class)
3. ▶ ResNet model graph
4. ▶ DataLoader / dataset utils
5. ▶ Lightning Trainer ▶ back to model & PyTorch
6. ▶ Outputs (checkpoints, logs)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Training Scripts
    subgraph "Training Scripts"
        direction TB
        script_bpe["train_mini_bpe.py"]:::script
        script_mobilenet["train_mini_mobilenet.py"]:::script
        script_resnet["train_mini_resnet.py"]:::script
        script_unet["train_mini_unet.py"]:::script
        script_vit["train_mini_vit.py"]:::script
        script_vqvae["train_mini_vqvae.py"]:::script
    end

    %% Model Library
    subgraph "Model Library"
        direction TB
        mbpe["mini_bpe\n• config.py\n• bpe.py\n• utils.py"]:::pkg
        mmobilenet["mini_mobilenet\n• config.py\n• mobilenet.py\n• dsc.py"]:::pkg
        mresnet["mini_resnet\n• config.py\n• resnet.py"]:::pkg
        munet["mini_unet\n• config.py\n• unet.py\n• dataset.py\n• utils.py"]:::pkg
        mvit["mini_vit\n• config.py\n• vit.py\n• transformer.py\n• utils.py"]:::pkg
        mvqvae["mini_vqvae\n• config.py\n• vqvae.py\n• vae.py\n• vq.py"]:::pkg
    end

    %% Orchestration Flow
    script_bpe -->|hyperparameters| mbpe
    script_mobilenet -->|hyperparameters| mmobilenet
    script_resnet -->|hyperparameters| mresnet
    script_unet -->|hyperparameters| munet
    script_vit -->|hyperparameters| mvit
    script_vqvae -->|hyperparameters| mvqvae

    %% Training Execution
    subgraph "Training Execution"
        direction TB
        trainer["Lightning Trainer"]:::framework
    end

    mbpe -->|model graph| trainer
    mmobilenet -->|model graph| trainer
    mresnet -->|model graph| trainer
    munet -->|model graph| trainer
    mvit -->|model graph| trainer
    mvqvae -->|model graph| trainer

    trainer -->|training loop & checkpointing| pytorch["PyTorch"]:::framework
    trainer -->|training loop orchestration| lightning["PyTorch Lightning"]:::framework

    %% Outputs and Artifacts
    outputs["Checkpoints & Logs"]:::data
    trainer -->|outputs| outputs

    %% Auxiliary Artifacts
    imgs["Image Assets (imgs/)"]:::data
    metadata["README.md\nrequirements.txt"]:::data

    %% Click Events
    click mbpe "https://github.com/lemonmindyes/minidream/tree/main/mini_bpe/"
    click mmobilenet "https://github.com/lemonmindyes/minidream/tree/main/mini_mobilenet/"
    click mresnet "https://github.com/lemonmindyes/minidream/tree/main/mini_resnet/"
    click munet "https://github.com/lemonmindyes/minidream/tree/main/mini_unet/"
    click mvit "https://github.com/lemonmindyes/minidream/tree/main/mini_vit/"
    click mvqvae "https://github.com/lemonmindyes/minidream/tree/main/mini_vqvae/"

    click script_bpe "https://github.com/lemonmindyes/minidream/blob/main/train_mini_bpe.py"
    click script_mobilenet "https://github.com/lemonmindyes/minidream/blob/main/train_mini_mobilenet.py"
    click script_resnet "https://github.com/lemonmindyes/minidream/blob/main/train_mini_resnet.py"
    click script_unet "https://github.com/lemonmindyes/minidream/blob/main/train_mini_unet.py"
    click script_vit "https://github.com/lemonmindyes/minidream/blob/main/train_mini_vit.py"
    click script_vqvae "https://github.com/lemonmindyes/minidream/blob/main/train_mini_vqvae.py"

    click imgs "https://github.com/lemonmindyes/minidream/tree/main/imgs/"
    click metadata "https://github.com/lemonmindyes/minidream/blob/main/README.md"

    %% Styling
    classDef pkg fill:#e0f7fa,stroke:#0288d1,stroke-width:2px
    classDef script fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px
    classDef framework fill:#cfd8dc,stroke:#607d8b,stroke-width:2px,stroke-dasharray: 5 5
    classDef data fill:#f1f8e9,stroke:#33691e,stroke-width:2px,stroke-dasharray: 2 2
```
