# nvidia/aistore architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia/aistore
- Repository: https://github.com/nvidia/aistore

## Overview

Based on our analysis of the AIStore project’s file tree and README, the system is a full‐stack object storage solution specialized for AI workloads and petascale deep learning. Its design features a highly available, horizontally scalable storage cluster that supports both a native REST API and an S3‐compatible interface, along with in-depth support for offloading ETL operations and integration with external cloud and storage backends.

##### Main Components
- Control Plane – This includes the central coordination and management for node membership, metadata, and cluster configuration. Look at modules like “cmd/aisinit”, “cmd/authn” (authentication), and “cmn”, “core” for clustering, metadata, and node/state management.
- Data Plane – The actual object storage and data movement functions. This is represented by “ais/” (which contains backend logic, bucket management, replication, ETL offload, proxying), “fs” (file system interactions), “xact” (data transfer actions), and “reb” (rebalance, replication consistency).
- API and Request Processing – The system provides a REST API as well as an Amazon S3 API. The “api” directories (like “api/apc” and “api/authn”) and “cmd/cli” indicate that the system exposes a rich HTTP-based API for both management (CLI) and client operations.
- External Interfaces – This includes integration points for external services and backends (e.g., AWS, GCP, Azure, OCI) as seen in the “ais/backend” module and even the “python/aistore/sdk” which supports client and SDK usage. Also, the ETL modules provide offloading logic.
- Deployment & Orchestration – The “deploy” directories (with k8s, docker, and local deployment scripts) show that the project is designed to run on anything from a single Linux machine to a full-blown Kubernetes cluster.
- CLI & SDK – The project includes a command-line interface (“cmd/cli”) and a Python SDK (found under “python/aistore/sdk”) that help users interact with the system.
- Benchmarking, Testing, and Monitoring – The “bench”, “docs”, and “stats” directories indicate integrated tools for performance testing, monitoring (including Prometheus, StatsD integration), and diagnostics.

##### Relationships and Interactions
- The Gateway/Proxy layer (covered in “cmd/aisnode”, “cmd/cli”, and “api” modules) routes requests to the appropriate Control/Data nodes.
- The Control plane (with metadata management, cluster state, node management) communicates with the Data plane (object storage nodes) to maintain consistency, replication, and support for erasure coding.
- There is integration with external cloud storage backends and remote clusters indicating that nodes may forward or offload certain operations to these backend systems.
- Deployment and orchestration components (Kubernetes/Docker) run and manage many of these components, ensuring high availability and scaling.

##### Architectural Patterns & Design Principles
- Distributed, scalable, and modular design: The storage nodes, gateways, and supporting utilities are all built as loosely coupled components that allow scaling linearly.
- Separation of Control and Data planes: Control functions (cluster management, configuration, metadata) are distinct from data movement operations (data read, write, replication).
- API-first design: The system exposes well-defined REST and S3 API interfaces.
- Extensibility through plug-in architectures: The ETL, authentication, and multi-backend support can be conceptualized as optional modules swappable at runtime.
- Resilience and self-healing: The presence of a robust “reb” (rebalance) module and distributed statistics/monitoring symbolizes fault-tolerance.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    Clients["Clients (CLI, SDK, S3 Clients)"]:::client

    %% API & Request Processing Subgraph
    subgraph "API and Request Processing"
        API["API Gateway (REST/S3)"]:::api
        CLI["CLI Interface"]:::api
    end

    %% Control Plane Subgraph
    subgraph "Control Plane"
        AISInit["AISInit (cmd/aisinit)"]:::control
        Authn["Authentication (cmd/authn)"]:::control
        CMN["CMN (cmn)"]:::control
        Core["Core (core)"]:::control
    end

    %% Data Plane Subgraph
    subgraph "Data Plane"
        AIS["AIS Module (ais)"]:::data
        FS["File System (fs)"]:::data
        Xact["Data Transfer (xact)"]:::data
        Reb["Rebalance (reb)"]:::data
        ETL["ETL Module"]:::data
    end

    %% External Interfaces Subgraph
    subgraph "External Interfaces"
        Backend["Backend Integrations"]:::external
        PySDK["Python SDK"]:::external
    end

    %% Deployment & Orchestration Subgraph
    subgraph "Deployment & Orchestration"
        Deploy["Deployment Scripts"]:::deploy
    end

    %% Benchmarking, Testing, and Monitoring Subgraph
    subgraph "Benchmarking, Testing, Monitoring"
        Bench["Benchmarking Tools"]:::monitor
        Stats["Stats & Monitoring"]:::monitor
        Docs["Documentation & Tutorials"]:::monitor
    end

    %% Connections
    Clients -->|"access"| API
    Clients -->|"uses"| PySDK

    API -->|"routes-to"| AISInit
    API -->|"routes-to"| Authn
    API -->|"routes-to"| AIS

    CLI -->|"manages"| AISInit
    CLI -->|"manages"| Authn

    AISInit -->|"coordinates"| AIS
    Authn -->|"secures"| AIS
    CMN -->|"manages"| AIS
    Core  -->|"controls"| AIS

    AIS -->|"triggers"| ETL

    AIS ---|"integrates"| Backend

    Deploy ---|"orchestrates"| AISInit
    Deploy ---|"orchestrates"| AIS
    Deploy ---|"orchestrates"| API

    Stats ---|"monitors"| AISInit
    Stats ---|"monitors"| AIS
    Stats ---|"monitors"| API

    Bench ---|"tests"| AIS
    Docs ---|"guides"| CLI

    %% Styling classes
    classDef client fill:#CCCCCC,stroke:#333,stroke-width:2px;
    classDef api fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef control fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef data fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef deploy fill:#FF7F7F,stroke:#333,stroke-width:2px;
    classDef monitor fill:#FFB6C1,stroke:#333,stroke-width:2px;

    %% Click Events for Control Plane
    click AISInit "https://github.com/nvidia/aistore/blob/main/cmd/aisinit/config.go"
    click Authn "https://github.com/nvidia/aistore/blob/main/cmd/authn/main.go"
    click CMN "https://github.com/nvidia/aistore/blob/main/cmn/api.go"
    click Core "https://github.com/nvidia/aistore/blob/main/core/backend.go"

    %% Click Events for Data Plane
    click AIS "https://github.com/nvidia/aistore/blob/main/ais/proxy.go"
    click FS "https://github.com/nvidia/aistore/blob/main/fs/api.go"
    click Xact "https://github.com/nvidia/aistore/blob/main/xact/api.go"
    click Reb "https://github.com/nvidia/aistore/blob/main/reb/bcast.go"
    click ETL "https://github.com/nvidia/aistore/blob/main/ais/etlmeta.go"

    %% Click Events for API & Request Processing
    click API "https://github.com/nvidia/aistore/blob/main/api/s3.go"
    click CLI "https://github.com/nvidia/aistore/blob/main/cmd/cli/main.go"

    %% Click Events for External Interfaces
    click Backend "https://github.com/nvidia/aistore/blob/main/ais/backend/aws.go"
    click PySDK "https://github.com/nvidia/aistore/blob/main/python/aistore/sdk/ais_source.py"

    %% Click Events for Deployment & Orchestration
    click Deploy "https://github.com/nvidia/aistore/tree/main/deploy/dev/"

    %% Click Events for Benchmarking, Testing, and Monitoring
    click Bench "https://github.com/nvidia/aistore/tree/main/bench/micro/"
    click Stats "https://github.com/nvidia/aistore/blob/main/stats/api.go"
    click Docs "https://github.com/nvidia/aistore/blob/main/docs/cli.md"
```
