# ivy-llc/ivy architecture

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

- Interactive diagram: https://gitdiagram.com/ivy-llc/ivy
- Repository: https://github.com/ivy-llc/ivy

## Overview

The Ivy project is a library engineered to convert machine learning (ML) code between various frameworks (for example, converting PyTorch, TensorFlow, JAX, and NumPy code). Its purpose is not just to “wrap” or “port” code, but also to provide two core functionalities:
1. Transpilation of functions, models, or even entire libraries from one framework’s API to another (using ivy.transpile).
2. Tracing of computational graphs (using ivy.trace_graph) to produce an optimized, framework‐native representation.

Because the file tree covers hundreds of files spread across directories like “ivy/”, “ivy/transpiler”, “ivy/tracer”, “ivy/engines”, “ivy/functional”, “ivy/stateful”, “ivy/module”, and many “ivy_tests/” directories, we can deduce a strong modular design:

Main components:
- Core API & Base Library (located under the “ivy/” directory):
– Contains essential functionalities including data classes, functional APIs, stateful operations, and modular wrappers.
– Manages core abstractions and language constructs (e.g., arrays, containers, modules) that allow Ivy to be framework agnostic.

- Transpiler Module (located in “ivy/transpiler/”):
– Implements the code conversion pipeline.
– Manages transformation configurations, translation rules, transformer passes, and caching.
– Organizes submodules such as configurations, transformations, transformers, and translators.
– Interfaces with the ivy.transpile() function which is the user-point entry to convert code modules/classes/functions.

- Tracer Module (located in “ivy/tracer/”):
– Provides graph extraction functionality.
– Converts wrapped functions into an efficient computational graph (using ivy.trace_graph).
– Handles control flow, AST, and intermediate representations for later optimization.

- Engine/Backend Integration (located in “ivy/engines/” and “ivy/functional/backends/”):
– Contains subdirectories for specific backends (like XLA, torch, tensorflow, etc.).
– Provides low-level wrappers to bridge Ivy’s generic operations to the native operations of the targeted ML framework.

- Wrapper/State & Module Layers (directories “ivy/module”, “ivy/stateful”, “ivy/wrappers”):
– Provide high-level abstractions that turn transpiled code into framework-specific modules.
– Enable users to interact with converted models in a native way.

- Testing & Documentation Infrastructure:
– Large test directory (ivy_tests/) for unit, integration, and transpiler tests ensures correctness across multiple frameworks.
– Documentation (docs/) and continuous integration workflows under “.github/” indicate a focus on maintainability and developer experience.

##### Begin by visually separating the system into distinct layers. For Ivy, you would have
- Client/Entry Layer: The user’s code that calls ivy.transpile() or ivy.trace_graph().
- API Layer: Exposed functions (ivy.transpile, ivy.trace_graph) that accept source code, configuration (e.g., “source” and “target” frameworks) and input arguments.
- Core Processing Pipeline – broken into:
- Parsing & Intermediate Representation: Processes abstract syntax trees (AST) and code transformations.
- Transformation & Translation Engine: Applies transformer modules (from ivy/transpiler/transformers and translations) to produce the target code.
- Graph-Generation Engine: For ivy.trace_graph, extract a computational graph and then “compile” it to a target framework.
- Backend Abstraction Layer: Contains framework-specific “engines” and “functional/backends” where the converted code is mapped to native operations.
- Output Layer: The final transpiled model/function or traced graph that executes using native implementations for TensorFlow, PyTorch, JAX, etc.

- From “User Code” to “API Layer” (calling ivy.transpile/trace_graph).
- From the API Layer into the “Transpiler Module”, which then intersects with “Transformation Engine” and “Graph Generation”.
- Additionally, include ancillary components:
- Testing (ivy_tests) and Documentation (docs) can be represented as supporting layers that ensure quality and developer guidance.
- Major interactions:
- “Transpile”: Accepts a function/model with a “source” framework and outputs a transpiled version in the “target” framework.
- “Trace Graph”: Extracts an optimized graph from a given function.
- “Engine Mappings”: Show that compatibility with multiple ML frameworks is provided via dedicated backend modules.

##### Architectural Patterns & Design Principles
- Modularity: Each major functionality (transpiling, tracing, engine abstraction) is encapsulated in its own submodule.
- Separation of Concerns: The project cleanly separates the core transformation logic from framework-specific implementations.
- Extensibility: With dedicated directories for transformer configurations, translations, and backend support, new rules or frameworks can be added without disturbing other parts.
- Test-Driven Development: The large ivy_tests directory signifies layered tests covering unit and integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point and API Layer
    A["User Code"]:::entry
    B["Ivy API (transpile/trace_graph)"]:::api
    A -->|"calls"| B

    %% Core Processing Pipeline
    subgraph "Core Processing Pipeline"
        direction TB
        C["Core Library Components"]:::core
        D["Transpiler Component"]:::transpiler
        E["Graph Tracing Component"]:::tracer
        C --> D
        C --> E
    end

    B -->|"provides_input"| C

    %% Transpiler Details
    subgraph "Transpiler Details"
        direction TB
        D1["Configurations"]:::trans
        D2["Transformers"]:::trans
        D3["Translations"]:::trans
        D --> D1
        D --> D2
        D --> D3
    end

    %% Graph Tracing Details
    subgraph "Graph Tracing Details"
        direction TB
        E1["AST Processing"]:::tracing
        E2["Graph Optimization"]:::tracing
        E --> E1
        E --> E2
    end

    %% Backend Integration and Output
    F["Backend Adapter (Engine Integration)"]:::backend
    D1 -->|"transformed_IR"| F
    D2 -->|"transformed_IR"| F
    D3 -->|"transformed_IR"| F
    E1 -->|"extracted_graph"| F
    E2 -->|"optimized_graph"| F

    %% Wrapper, State & Module Layers (Ancillary)
    K["Wrapper/State & Module Layers"]:::wrapper
    F -->|"uses"| K

    %% Final Native Execution Environment
    G["Native Framework Execution Environment"]:::native
    F -->|"native_function/module"| G

    %% Supporting Testing & Documentation
    H["Testing (ivy_tests/)"]:::test
    I["Documentation (docs/)"]:::docs
    G -->|"feedback"| C
    H -->|"ensures_quality"| C
    I -->|"guidance"| C

    %% Click Events for Component Mapping
    click C "https://github.com/ivy-llc/ivy/tree/main/ivy/"
    click D "https://github.com/ivy-llc/ivy/tree/main/ivy/transpiler/"
    click E "https://github.com/ivy-llc/ivy/tree/main/ivy/tracer/"
    click F "https://github.com/ivy-llc/ivy/tree/main/ivy/engines/"
    click F "https://github.com/ivy-llc/ivy/tree/main/ivy/functional/backends/"
    click K "https://github.com/ivy-llc/ivy/tree/main/ivy/module/"
    click K "https://github.com/ivy-llc/ivy/tree/main/ivy/stateful/"
    click K "https://github.com/ivy-llc/ivy/tree/main/ivy/wrappers/"
    click H "https://github.com/ivy-llc/ivy/tree/main/ivy_tests/"
    click I "https://github.com/ivy-llc/ivy/tree/main/docs/"

    %% Styles
    classDef entry fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef core fill:#cce0ff,stroke:#333,stroke-width:2px;
    classDef transpiler fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef tracer fill:#ccffff,stroke:#333,stroke-width:2px;
    classDef trans fill:#b3ffb3,stroke:#333,stroke-width:2px;
    classDef tracing fill:#b3e6ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#ffd699,stroke:#333,stroke-width:2px;
    classDef native fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef wrapper fill:#fff0b3,stroke:#333,stroke-width:2px;
    classDef test fill:#ffdb99,stroke:#333,stroke-width:2px;
    classDef docs fill:#d9ffcc,stroke:#333,stroke-width:2px;
```
