# geragzgm/modelzoo architecture

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

- Interactive diagram: https://gitdiagram.com/geragzgm/modelzoo
- Repository: https://github.com/geragzgm/modelzoo

## Overview

##### Project Type and Purpose
- It is an open-source CLI application for standardized training and inference of CNN architectures (AlexNet, ResNet, VGG, MobileNet, etc.).
- It uses JSON configs to drive experiments, supports multiple dataset backends (CIFAR-10, Kaggle), and provides reproducible checkpointing.

##### File Structure
- Top level:
- `_configs/` contains JSON files for each model.
- `modelzoo/` Python package.
- `pyproject.toml` & `setup.py` for packaging.
- Inside `modelzoo/`:
- `cli.py`, `main.py` – CLI entry points.
- `build_config.py` – loads and validates JSON.
- `dataset_loaders/` – abstracts data ingestion.
- `models/` – plugin directories per model, all inheriting from `base_models.py`.
- `train/` – training/inference logic in `base_train.py`, `inference.py`, and classification routines.
- `utils.py` – shared utilities.
- `tests/` – unit tests (e.g., registry tests).

##### README for Architectural Insights
- Config-driven: everything from optimizer to transforms is JSON-specified.
- Extensible: adding a new model means dropping its folder into `models/` and updating config.
- CLI patterns: commands (`--run_type train` or `inference`) orchestrate workflows.

##### Main Components
a. CLI Layer
– `modelzoo` shell command → `main.py` & `cli.py`
– Parses args, chooses “train” vs. “inference.”
b. Configuration Loader
– `build_config.py` reads `_configs/*.json`
– Produces a typed config object.
c. Dataset Loader
– `dataset_loaders/base_dataset.py` and concrete loaders.
– Interfaces with local CIFAR-10 or Kaggle API.
d. Model Registry & Factory
– `models/base_models.py` + per-model `model.py`
– Registry pattern: `cli` asks for “VGG16” → factory returns the class.
e. Training & Inference Engine
– `train/base_train.py`: orchestrates epochs, batching, checkpointing.
– `train/inference.py`: runs forward passes, outputs metrics.
– `train/src/classification.py`: loss, metrics, callbacks.
f. Checkpoint & Artifacts
– Checkpoints, logs written under `models/<ModelName>/chkpt/`.
g. External Services & Data
– Kaggle API for dataset download.
– File system for config and model saving.
h. Testing
– `tests/test_registers.py`: ensure model registration integrity.

##### Relationships & Interactions
- Bidirectional: Config Loader ↔ Model Factory (to match model names).
- Data flow: Raw Data → Transforms → Batches → Model → Loss → Optimizer.

##### Architectural Patterns & Principles
- Plugin/Registry Pattern for models & dataset loaders.
- Configuration-Driven Design: all parameters decoupled from code.
- Separation of Concerns: CLI, config parsing, data loading, model definitions, training logic all isolated in their own modules.
- Reproducibility via checkpointing and seedable loaders.

##### Technologies & Frameworks
- Python 3 (packaged via setup.py / Poetry).
- Likely PyTorch (implied by `.pth` checkpoints).
- Kaggle API for external data.
- JSON for configs.

##### Detail Level
- Python modules as subcomponents where relevant.
- Methods:
- `build_config.load()`
- `DatasetLoader.get_dataloader()`
- `ModelFactory.create_model()`
- `BaseTrain.train_epoch()` / `Inference.run()`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI_Main["main.py"]:::cli
        CLI_CLI["cli.py"]:::cli
    end

    %% Config & Registry Layer
    subgraph "Config & Registry" 
        direction TB
        ConfigLoader["build_config.py"]:::config
        JSONConfigs["JSON Configs"]:::persistence
        ModelRegistry["base_models.py"]:::model
    end

    %% Data Layer
    subgraph "Dataset Loader" 
        direction TB
        BaseDataset["base_dataset.py"]:::data
        ConcreteLoaders["Concrete Loaders"]:::data
    end

    %% Model Plugin Layer
    subgraph "Model Plugins"
        direction TB
        VGGModel["VGG Model (model.py)"]:::model
        ResNetModel["ResNet Model (model.py)"]:::model
    end

    %% Engine Layer
    subgraph "Engine"
        direction TB
        TrainEngine["base_train.py"]:::engine
        InferenceEngine["inference.py"]:::engine
        Classification["classification.py"]:::engine
    end

    %% Utilities
    Utils["utils.py"]:::utils

    %% Persistence & External
    subgraph "Persistence & External"
        direction TB
        Checkpoints["Checkpoint Store"]:::persistence
        KaggleAPI["Kaggle API"]:::external
    end

    %% Testing
    Tests["test_registers.py"]:::test

    %% Connections
    CLI_Main -->|calls| CLI_CLI
    CLI_CLI -->|uses| ConfigLoader
    ConfigLoader -->|loads| JSONConfigs
    ConfigLoader -->|queries| ModelRegistry
    ConfigLoader -->|provides config| BaseDataset
    ConfigLoader -->|provides config| ModelRegistry
    BaseDataset -->|instantiates| ConcreteLoaders
    ConcreteLoaders -->|downloads data| KaggleAPI
    ModelRegistry -->|returns model class| VGGModel
    ModelRegistry -->|returns model class| ResNetModel
    VGGModel -->|used by| TrainEngine
    ResNetModel -->|used by| TrainEngine
    TrainEngine -->|calls| Classification
    TrainEngine -->|saves| Checkpoints
    InferenceEngine -->|loads| Checkpoints
    InferenceEngine -->|reports metrics| Classification
    CLI_CLI -->|triggers| TrainEngine
    CLI_CLI -->|triggers| InferenceEngine

    %% Utilities usage
    ConfigLoader -.->|helper functions| Utils
    BaseDataset -.->|helper functions| Utils
    ModelRegistry -.->|helper functions| Utils
    TrainEngine -.->|helper functions| Utils
    InferenceEngine -.->|helper functions| Utils

    %% Testing relationships
    Tests -->|validates| ModelRegistry

    %% Click Events
    click CLI_Main "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/main.py"
    click CLI_CLI "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/cli.py"
    click ConfigLoader "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/build_config.py"
    click JSONConfigs "https://github.com/geragzgm/modelzoo/blob/master/_configs/resnet18.json"
    click BaseDataset "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/dataset_loaders/base_dataset.py"
    click ModelRegistry "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/models/base_models.py"
    click VGGModel "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/models/VGG/src/model.py"
    click TrainEngine "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/train/base_train.py"
    click InferenceEngine "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/train/inference.py"
    click Classification "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/train/src/classification.py"
    click Utils "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/utils.py"
    click Checkpoints "https://github.com/geragzgm/modelzoo/tree/master/modelzoo/models/ResNet/chkpt/"
    click Tests "https://github.com/geragzgm/modelzoo/blob/master/modelzoo/tests/test_registers.py"

    %% Styles
    classDef cli fill:#D0E7FF,stroke:#0366d6,stroke-width:1px;
    classDef config fill:#E6F5D0,stroke:#238636,stroke-width:1px;
    classDef data fill:#FFF5D0,stroke:#D68C06,stroke-width:1px;
    classDef model fill:#FFE0B2,stroke:#BF5F00,stroke-width:1px;
    classDef engine fill:#FFE6F0,stroke:#D33682,stroke-width:1px;
    classDef persistence fill:#F0F0F0,stroke:#6A737D,stroke-width:1px;
    classDef external fill:#E0F7FA,stroke:#00796B,stroke-width:1px;
    classDef utils fill:#F3E8FF,stroke:#6F42C1,stroke-width:1px;
    classDef test fill:#FFEBE6,stroke:#DB1F48,stroke-width:1px;
```
