# sproc01/branchyyolo architecture

> Architecture diagram of the GitHub repository sproc01/branchyyolo, 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/sproc01/branchyyolo
- Repository: https://github.com/sproc01/branchyyolo

## Overview

##### Project Type and Purpose
- This is a deep learning object detection project, specifically implementing a variant of the YOLO architecture – BranchyYOLO – which introduces a two-branch topology for detecting table game pieces. Additionally, it includes an ablated version of YOLOv9-C used for comparative studies.
- The project leverages PyTorch and depends on an external YOLOv9 implementation for some of its functionality.

##### Analyzing the File Structure
- Top-Level Files:
- Files like run.py, Detection.ipynb, and yaml configuration files (BranchyYOLO.yaml, AblatedYOLOv9-C.yaml, hyp.yaml, coco.yaml) are the backbone of training, testing, and configuration.
- README.md and Report.pdf provide project documentation and details.
- Directory “Model”:
- Contains separate directories for BranchyYOLO and AblatedYOLOv9-C, each with subdirectories for training (e.g., Train_synthetic, Train_synthetic_real) holding the best trained model weights.
- Other Files:
- The Jupyter Notebook (Detection.ipynb) indicates a usage context where users might perform object detection, pointing to an end-to-end pipeline from training to inference.
- This structure suggests a design where different model definitions (configured by separate YAML files) are trained and evaluated with common pipelines (run.py).

##### Architectural Components
a. Model Definitions:
- BranchyYOLO model (defined in BranchyYOLO.yaml) and AblatedYOLOv9-C model (defined in AblatedYOLOv9-C.yaml).
b. Training Pipeline:
- run.py acts as the orchestration layer to train and test models.
- Configuration files: hyp.yaml (hyperparameters) and coco.yaml (dataset configuration).
c. Data Input / Dataset:
- The dataset is referenced via coco.yaml. Note that the actual dataset isn’t included, but it’s integral to the system's function.
d. Inference Pipeline:
- Detection.ipynb for running object detection in images, likely using the trained model weights.
e. Model Weights Storage:
- The Model directory stores the different trained model snapshots for both the BranchyYOLO and Ablated YOLO versions.
f. External Dependencies:
- PyTorch and the officially referenced YOLOv9 implementation are key dependencies used in the training and model building process.

- Data Layer: Represent datasets and configuration (coco.yaml).
- Training Engine: Denote run.py which controls the training process and tests. Include sub-components like data loading, pre-processing, forward/backward pass, and evaluation.
- Hyperparameter and Configuration Manager: Represent hyp.yaml as a module feeding configuration details.
- Inference: Include a separate component for Detection.ipynb which illustrates detection/inference flow.
- Branching from run.py into two separate training workflows (one for BranchyYOLO and one for the ablated variant), then converging into model evaluation and inference.
- Notes on Architectural Patterns:
- That the design follows a modular deep learning pipeline pattern with clear separation between model definition, training, and inference.
- That the abstraction allows for easy swapping and comparison between different model topologies (BranchyYOLO vs. AblatedYOLOv9-C).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        coco["Dataset Config (coco.yaml)"]:::config
        hyp["Hyperparameters (hyp.yaml)"]:::config
    end

    %% Training Engine
    subgraph "Training Engine"
        runpy["Training Orchestrator (run.py)"]:::pipeline
    end

    %% BranchyYOLO Training Path
    subgraph "BranchyYOLO Training"
        branchyModel["BranchyYOLO Model (BranchyYOLO.yaml)"]:::model
        branchyWeights["Model Weights (BranchyYOLO)"]:::storage
    end

    %% AblatedYOLOv9-C Training Path
    subgraph "AblatedYOLOv9-C Training"
        ablatedModel["AblatedYOLOv9-C Model (AblatedYOLOv9-C.yaml)"]:::model
        ablatedWeights["Model Weights (AblatedYOLOv9-C)"]:::storage
    end

    %% Inference Layer
    subgraph "Inference"
        detection["Inference Module (Detection.ipynb)"]:::pipeline
    end

    %% External Dependency
    yolov9dep["YOLOv9 Official Implementation"]:::external

    %% Connections from Configuration to Training Engine
    coco -->|"feeds"| runpy
    hyp  -->|"feeds"| runpy

    %% Connections from Training Engine to Model Branches
    runpy -->|"initiates"| branchyModel
    runpy -->|"initiates"| ablatedModel

    %% Connections from Model Definitions to Model Weights Storage
    branchyModel -->|"saves weights"| branchyWeights
    ablatedModel -->|"saves weights"| ablatedWeights

    %% Connections from Training Paths to Inference
    branchyWeights -->|"outputs"| detection
    ablatedWeights -->|"outputs"| detection

    %% External Dependency Connection
    runpy -->|"uses"| yolov9dep

    %% Click Events
    click coco "https://github.com/sproc01/branchyyolo/blob/main/coco.yaml"
    click hyp "https://github.com/sproc01/branchyyolo/blob/main/hyp.yaml"
    click runpy "https://github.com/sproc01/branchyyolo/blob/main/run.py"
    click branchyModel "https://github.com/sproc01/branchyyolo/blob/main/BranchyYOLO.yaml"
    click ablatedModel "https://github.com/sproc01/branchyyolo/blob/main/AblatedYOLOv9-C.yaml"
    click detection "https://github.com/sproc01/branchyyolo/blob/main/Detection.ipynb"
    click branchyWeights "https://github.com/sproc01/branchyyolo/tree/main/Model/BranchyYOLO"
    click ablatedWeights "https://github.com/sproc01/branchyyolo/tree/main/Model/AblatedYOLOv9-C"

    %% Styles
    classDef config fill:#afe9ff,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#ffdea1,stroke:#333,stroke-width:2px;
    classDef model fill:#c2e7d9,stroke:#333,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#880000,stroke-width:2px;
    classDef storage fill:#f7d794,stroke:#996600,stroke-width:2px;
```
