# mosaicml/composer architecture

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

- Interactive diagram: https://gitdiagram.com/mosaicml/composer
- Repository: https://github.com/mosaicml/composer

## Overview

##### Main Components
- Trainer & Training Loop – This is at the heart of Composer (found in composer/trainer/trainer.py), encapsulating the training loop, scheduling of events, and integration with callbacks.
- Callback System – Modules in composer/callbacks enable insertion of custom logic (e.g., early stopping, logging, speed monitoring) at various training events.
- Algorithms – Located under composer/algorithms, these modules implement training speedups and modifications (such as Label Smoothing, CutMix, ChannelsLast, etc.) to be applied during training.
- Core Components – Under composer/core, you have the definition of algorithm and callback interfaces, event handling, state management, and timing.
- Logging & Monitoring – Loggers in composer/loggers provide integrations with external platforms (Weights & Biases, MLFlow, Neptune, etc.) and support both in-memory and file-based logging.
- Checkpointing – The checkpoint directory and related files (composer/checkpoint) handle saving, loading, and elastic sharded checkpointing (to support changes in hardware during distributed training).
- Distributed & Device Management – Components in composer/devices and composer/distributed abstract hardware types (CPU, GPU, TPU, etc.) and parallelism (e.g., FSDP, DDP) to support scale-out training.
- Model Building – Composer models and tasks under composer/models and composer/models/tasks provide support for various model types (including custom Hugging Face integration).
- CLI & User Interaction – The CLI layer (composer/cli) and examples illustrate how users launch training jobs, configure the environment, and integrate with Docker/containerized environments.

##### Relationships and Interactions
- Trainer as a central orchestrator that initializes the model, the training loop, and integrates with callbacks and algorithms.
- A data flow from the Dataset (user’s dataloader) through the Trainer to the underlying model, and then back to logging systems.
- External integrations (tracking systems, cloud storage for checkpoint handling, Docker, and CI/CD pipelines via GitHub workflows) as boundaries that interface with the core framework.

##### Architectural Patterns & Design Principles
- Modularity: The code structure is highly modular. Each major component (Trainer, Algorithms, Callbacks, etc.) is self-contained and extends through clearly defined interfaces.
- Plugin Architecture: The Trainer supports pluggable algorithms and callbacks, following a design that lets users customize training dynamically.
- Abstraction & Separation of Concerns: Core, devices, distributed, and logging components handle specific concerns, making the system easier to extend.
- Configuration & Extensibility: With many configuration scripts (Makefile, Dockerfiles, and pre-commit configurations), the system is built for reproducibility and integration in varied environments.

##### Diagramming Relevant Technologies & Libraries
- Distributed Training: Mention abstractions around PyTorch DDP, FSDP, and additional cloud integrations.
- Docker & CI/CD: Include CI components (GitHub workflows) and Docker layers that support containerized execution.
- External Services: Represent loggers that integrate with services like WandB, MLFlow, and others.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        CLI["CLI & User Interaction"]:::external
    end

    %% Core Training Engine
    subgraph "Core Training Engine"
        Trainer["Trainer & Training Loop"]:::core
        Core["Core Components"]:::core
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        Callback["Callback System"]:::module
        Algorithms["Algorithms/Speedup Methods"]:::module
        Logging["Logging & Monitoring"]:::module
        Checkpoint["Checkpointing"]:::module
    end

    %% Distributed and Device Management Layer
    subgraph "Distributed & Device Management"
        Distributed["Distributed Management"]:::module
        Devices["Device Management"]:::module
    end

    %% Model Layer
    subgraph "Model Layer"
        ModelBuilding["Model Building"]:::module
        ModelTasks["Model Tasks"]:::module
    end

    %% Data Flow
    CLI -->|"initiates"| Trainer
    Trainer -->|"coordinates"| Core
    Trainer -->|"triggers"| Callback
    Trainer -->|"applies"| Algorithms
    Trainer -->|"logs to"| Logging
    Trainer -->|"saves/loads"| Checkpoint
    Trainer -->|"orchestrates"| Distributed
    Trainer -->|"orchestrates"| Devices
    Trainer -->|"utilizes"| ModelBuilding
    Trainer -->|"utilizes"| ModelTasks

    %% Click Events
    click CLI "https://github.com/mosaicml/composer/tree/main/composer/cli/"
    click Trainer "https://github.com/mosaicml/composer/blob/main/composer/trainer/trainer.py"
    click Callback "https://github.com/mosaicml/composer/tree/main/composer/callbacks/"
    click Algorithms "https://github.com/mosaicml/composer/tree/main/composer/algorithms/"
    click Core "https://github.com/mosaicml/composer/tree/main/composer/core/"
    click Logging "https://github.com/mosaicml/composer/tree/main/composer/loggers/"
    click Checkpoint "https://github.com/mosaicml/composer/tree/main/composer/checkpoint/"
    click Distributed "https://github.com/mosaicml/composer/tree/main/composer/distributed/"
    click Devices "https://github.com/mosaicml/composer/tree/main/composer/devices/"
    click ModelBuilding "https://github.com/mosaicml/composer/tree/main/composer/models/"
    click ModelTasks "https://github.com/mosaicml/composer/tree/main/composer/models/tasks/"

    %% Styles
    classDef core fill:#B3D4FC,stroke:#1F8AC0,stroke-width:2px;
    classDef module fill:#FDE68A,stroke:#F59E0B,stroke-width:2px;
    classDef external fill:#D1FAE5,stroke:#10B981,stroke-width:2px;
```
