# openxla/shardy architecture

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

- Interactive diagram: https://gitdiagram.com/openxla/shardy
- Repository: https://github.com/openxla/shardy

## Overview

##### Project Type and Purpose
- Shardy is a compiler/transformation system built on MLIR. It implements a dialect-agnostic tensor partitioning approach used for sharding in systems like JAX, integrating ideas from modern compiler infrastructures (e.g., GSPMD and PartIR).
- The system is built with Bazel as its primary build tool and focuses on defining a custom MLIR dialect (under shardy/dialect/sdy), transformation passes, and integrations with C and Python.

##### Analyzing the File Structure
- Notice key top-level directories:
- The “shardy” directory is the core, containing subdirectories for common utilities, dialect definitions ("dialect/sdy" for IR definitions and tests), transformation passes (export, import, propagation), integration modules (under integrations/c and integrations/python), round-trip import functionality, and tooling.
- "third_party" holds external dependencies related to LLVM, MLIR, and StableHLO, highlighting the system’s reliance on these compiler infrastructure components.
- Build configuration files like WORKSPACE, MODULE.bazel, and various Bazel scripts indicate that the build orchestration is integrated into the architecture.
- The directory structure reflects a modular design: each submodule (IR definitions, transforms, integrations, etc.) is separated clearly, which suggests layering common in compiler design (front-end dialect, transformation passes, and integration/back-end tools).

##### Key Architectural Components
a. MLIR IR and Dialect Components:
- Dialect definition (shardy/dialect/sdy) where all the IR components, op definitions, custom attributes, and tests are located.
- Point out that MLIR tablegen files (*.td) and associated C++ source files define the IR constructs.
b. Transformation Passes:
- Transformation infrastructure split into several subareas:
- Export Passes (shardy/dialect/sdy/transforms/export): Responsible for translating or modifying IR for output.
- Import Passes (shardy/dialect/sdy/transforms/import): Handling the import pipeline.
- Propagation Passes (shardy/dialect/sdy/transforms/propagation): Implementing sharding propagation mechanisms including experimental and debugging utilities.
- That these passes operate on the IR defined in the dialect modules.
c. Common Utilities and Shared Components:
- “shardy/common” contains utilities and shared implementations (for example, file utilities and module operations).
d. Integration Layers:
- The integrations directory (both “integrations/c” and “integrations/python”) provides bindings to use Shardy from other languages and toolchains.
e. Round-trip Import Module:
- “shardy/round_trip_import” contains code to facilitate the reimport/export of sharding information, ensuring that the system’s transformations are reversible or verifiable.
f. Tooling:
- Under “shardy/tools” you find binaries (sdy_opt_main.cc, sdy_translate_main.cc) serving as interfaces or drivers for executing the partitioning and translation tasks.
g. External Dependencies:
- The “third_party” directory, which includes LLVM, MLIR helper libraries, and StableHLO, should be represented as external services or libraries that the core system relies upon.
h. Build and Configuration Infrastructure:
- Bazel configuration files (e.g., .bazelrc, WORKSPACE, MODULE.bazel, etc.) should be noted, showing that build orchestration is central to the project’s integration.

##### Depicting Relationships and Interactions
- How the MLIR IR layer (the custom dialect) is fed into the various transformation passes.
- How transformation passes interact with both the “export” and “import” pipelines.
- Connections from the core compiler infrastructure out to the integration layers (C, Python) and tooling.
- The external dependencies (LLVM, StableHLO) feed into or are used by the dialect definitions and transformation passes.
- Data flows (for example, a typical pipeline might be: Input MLIR code → IR Construction via Shardy dialect → Transformation passes (propagation, export/import) → Optimized IR → Tooling for command-line invocation or integration).

##### Architectural Patterns and Design Principles
- Modularization: Each functional area (dialect definition, transformation passes, integration layers) is clearly separated.
- Extensibility: The structure supports adding new passes or integrations, as evidenced by the segregated directories and test suites.
- Compiler infrastructure layering: Follow standard compiler architecture (IR definition → transformation/optimization passes → backend or external tools) for clarity.
- Use of Bazel for consistent build and dependency management, which is vital for a system with multiple submodules and external libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment and Build layer
    ED["External Dependencies"]:::external
    BS["Bazel Build System"]:::build
    CU["Common Utilities"]:::common

    %% Core Compiler Infrastructure: MLIR Dialect
    MD["MLIR Dialect (IR, Tablegen, Tests)"]:::core

    %% Transformation Passes
    subgraph "Transformation Passes"
        TP_EXPORT["Export Pass"]:::pass
        TP_IMPORT["Import Pass"]:::pass
        TP_PROP["Propagation Pass"]:::pass
    end

    %% Merged Output from Transformation Passes
    OIR["Optimized IR"]:::optimized

    %% Integration & Tooling Layer
    subgraph "Integration & Tooling"
        CI["C Integration"]:::integration
        PI["Python Integration"]:::integration
        TO["Tooling (CLI)"]:::tooling
        RT["Round-trip Import"]:::integration
    end

    %% Arrows from Environment to Core
    ED --> MD
    BS --> MD
    CU --> MD

    %% Arrows from MLIR Dialect to Transformation Passes
    MD --> TP_EXPORT
    MD --> TP_IMPORT
    MD --> TP_PROP

    %% Arrows from Transformation Passes to Optimized IR
    TP_EXPORT --> OIR
    TP_IMPORT --> OIR
    TP_PROP --> OIR

    %% Arrows from Optimized IR to Integration & Tooling
    OIR --> CI
    OIR --> PI
    OIR --> TO
    OIR --> RT

    %% Styles
    classDef external fill:#e0e0e0,stroke:#555,stroke-width:2px;
    classDef build fill:#f0a,stroke:#333,stroke-width:2px;
    classDef common fill:#ffeb99,stroke:#333,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef pass fill:#c1e1c1,stroke:#333,stroke-width:2px;
    classDef optimized fill:#f9c,stroke:#333,stroke-width:2px;
    classDef integration fill:#fdd,stroke:#333,stroke-width:2px;
    classDef tooling fill:#d0e0ff,stroke:#333,stroke-width:2px;

    %% Click Events
    click MD "https://github.com/openxla/shardy/tree/main/shardy/dialect/sdy/ir"
    click TP_EXPORT "https://github.com/openxla/shardy/tree/main/shardy/dialect/sdy/transforms/export"
    click TP_IMPORT "https://github.com/openxla/shardy/tree/main/shardy/dialect/sdy/transforms/import"
    click TP_PROP "https://github.com/openxla/shardy/tree/main/shardy/dialect/sdy/transforms/propagation"
    click CU "https://github.com/openxla/shardy/tree/main/shardy/common"
    click CI "https://github.com/openxla/shardy/tree/main/shardy/integrations/c"
    click PI "https://github.com/openxla/shardy/tree/main/shardy/integrations/python"
    click RT "https://github.com/openxla/shardy/tree/main/shardy/round_trip_import"
    click TO "https://github.com/openxla/shardy/tree/main/shardy/tools"
    click ED "https://github.com/openxla/shardy/tree/main/third_party"
    click BS "https://github.com/openxla/shardy/tree/main/WORKSPACE"
```
