# deci-ai/super-gradients architecture

> Architecture diagram of the GitHub repository deci-ai/super-gradients, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deci-ai/super-gradients
- Repository: https://github.com/deci-ai/super-gradients

## Overview

##### Main Components
- Core Library & Common Modules: This covers “src/super_gradients/common” and its submodules (data types, environment, AWS/data connectors, logging, decorators, etc.). Mark these as foundational utilities that support the whole framework.
- Model Zoo and Architectures: Around “src/super_gradients/training/models” and “src/super_gradients/recipes” – these components define various classification, segmentation, detection, and pose estimation models along with predefined recipes (YoloNAS, DEKR, etc.).
- Training Pipeline: Include the training modules (located in “src/super_gradients/training”) that include dataloaders, datasets, loss functions, metrics, optimizers, callbacks, and pipelines. The Trainer and scripts like “train_from_recipe.py” reside here.
- Conversion and Inference: The “src/super_gradients/conversion” and “src/super_gradients/inference” modules handle the conversion (exporting to ONNX, TensorRT, etc.) as well as inference logic.
- Integration and Plugins: Highlight integration with external services/loggers (WandB, ClearML, DagsHub) as well as utility plugins. These can be represented as distinct connectors that interact with the training module.
- Testing & Documentation: Although not part of the runtime architecture, having a robust “tests” directory and “documentation” folder helps indicate that the system design places strong emphasis on modularity, reproducibility, and validation. These can be shown as supporting components.

##### Relationships and Data Flow
- The Trainer (from the training module) orchestrates the entire training lifecycle—interacting with:
- The Model Factory (in “models” or “factories”) that instantiates a given architecture from the Model Zoo or recipe.
- Data interfaces/dataloaders pulling data from various datasets (found in “training/datasets”).
- Callback and logging modules that interface with external plugins (wandb, clearml, etc.) for tracking the training progress.
- Before and after training, conversion utilities and inference modules transform trained models to production-ready formats.
- The recipes provide configuration and override default training parameters so that the same model can be easily adapted for fine-tuning or transfer learning.
- The common utilities provide shared services such as distributed training support (DDP), environment setup, and error handling that pervade the system.

##### Architectural Patterns and Design Principles
- Modular & Layered Architecture: The system is built as independent modules (common utilities, training, models, conversion) that interact through well-defined interfaces.
- Factory and Callback Patterns: Factories for model instantiation and extensive use of callbacks (phase callbacks, logging, learning rate scheduling) to decouple the training workflow.
- Extensibility: The use of registries and plugin integration allows easy extension to new model architectures, losses, datasets, and logging services.
- Production Readiness: Integration with model conversion (to ONNX/TensorRT) and deployment pipelines, along with distributed training support, makes the system suitable for production.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Layer
    subgraph "Core Library Layer"
        CoreLib["Core Library (src/super_gradients/common)"]:::core
    end

    %% Data & Model Components Layer
    subgraph "Data & Model Components"
        ModelZoo["Model Zoo & Recipes (src/super_gradients/training/models)"]:::model
    end

    %% Training Pipeline Layer
    subgraph "Training Pipeline Layer"
        Factory["Model Factory"]:::training
        DataInterface["Data Interfaces (dataloaders/datasets)"]:::training
        Trainer["Trainer (src/super_gradients/training)"]:::training
        SGTrainer["SG Trainer (src/super_gradients/sg_trainer)"]:::training
    end

    %% Conversion & Inference Layer
    subgraph "Conversion & Inference"
        Conversion["Conversion Module (src/super_gradients/conversion)"]:::conversion
        Inference["Inference Module (src/super_gradients/inference)"]:::conversion
    end

    %% Integration & Plugins Layer
    subgraph "Integration & Plugins"
        Plugins["Plugins & External Integrations (src/super_gradients/common/plugins)"]:::plugin
        WandB["WandB Integration (src/super_gradients/common/plugins/wandb)"]:::plugin
    end

    %% Testing & Documentation Layer
    subgraph "Testing & Documentation"
        Tests["Tests (tests)"]:::test
        Docs["Documentation (documentation)"]:::test
    end

    %% Relationships and Data Flow
    ModelZoo -->|"feeds"| Factory
    DataInterface -->|"supplies"| Trainer
    Factory -->|"instantiates"| Trainer
    Trainer -->|"orchestrates"| SGTrainer
    SGTrainer -->|"trains"| Conversion
    Conversion -->|"exports_to"| Inference
    Trainer <-->|"logs_with"| Plugins
    Plugins <-->|"integrates"| WandB
    CoreLib -->|"supports"| Trainer
    CoreLib -->|"supports"| DataInterface
    CoreLib -->|"supports"| Plugins
    CoreLib -->|"validatedBy"| Tests
    CoreLib -->|"validatedBy"| Docs

    %% Styles
    classDef core stroke:#2c3e50,fill:#85C1E9,stroke-width:2px;
    classDef model stroke:#2c3e50,fill:#AED6F1,stroke-width:2px;
    classDef training stroke:#2c3e50,fill:#A9DFBF,stroke-width:2px;
    classDef conversion stroke:#2c3e50,fill:#F9E79F,stroke-width:2px;
    classDef plugin stroke:#2c3e50,fill:#F5B7B1,stroke-width:2px;
    classDef test stroke:#2c3e50,fill:#D2B4DE,stroke-width:2px;

    %% Click Events
    click CoreLib "https://github.com/deci-ai/super-gradients/tree/master/src/super_gradients/common"
    click ModelZoo "https://github.com/deci-ai/super-gradients/tree/master/src/super_gradients/training/models"
    click Trainer "https://github.com/deci-ai/super-gradients/tree/master/src/super_gradients/training"
    click SGTrainer "https://github.com/deci-ai/super-gradients/tree/master/src/super_gradients/sg_trainer"
    click Conversion "https://github.com/deci-ai/super-gradients/tree/master/src/super_gradients/conversion"
    click Inference "https://github.com/deci-ai/super-gradients/tree/master/src/super_gradients/inference"
    click Plugins "https://github.com/deci-ai/super-gradients/tree/master/src/super_gradients/common/plugins"
    click WandB "https://github.com/deci-ai/super-gradients/tree/master/src/super_gradients/common/plugins/wandb"
    click Tests "https://github.com/deci-ai/super-gradients/tree/master/tests"
    click Docs "https://github.com/deci-ai/super-gradients/tree/master/documentation"
```
