# raydium-io/raydium-clmm architecture

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

- Interactive diagram: https://gitdiagram.com/raydium-io/raydium-clmm
- Repository: https://github.com/raydium-io/raydium-clmm

## Overview

##### Project Type & Purpose
- This project is an open-source on-chain program (smart contract) and its associated off-chain client.
- It implements a concentrated liquidity market maker for the Solana blockchain, allowing liquidity providers to restrict their liquidity to defined price ranges.
- The design includes both on-chain components (deployed via Anchor) and off-chain pieces that facilitate client interaction and instruction processing.

##### Analyzing the File Structure
- Top-level files such as .gitignore, Anchor.toml, Cargo.toml, and configuration files indicate a Rust-based project managed with Anchor.
- The “client” directory contains the off-chain client-side application. Within this, the “src/instructions” subfolder contains Rust modules that build various transaction instructions, including those for AMM functions and token-related operations.
- The “programs/amm” directory contains the on-chain program for the AMM. It is organized to include:
- Instructions (divided into administrative actions and user operations like swap, liquidity management, and position handling).
- Libraries for essential calculations (big number arithmetic, fixed-point math, liquidity math, tick math, etc.).
- State definitions that describe data structures for pools, positions, operation accounts, and oracles.
- Utility modules for account loading, token system interactions, and more.
- The use of Anchor and Cargo files reflects standard deployment workflows and integration with the Solana blockchain.

##### Core Components
- Client Application:
- Off-chain module in the “client” directory.
- Handles building and sending transactions, constructing instructions (for swaps, positions, etc.).
- Likely communicates with Solana’s RPC nodes.
- On-chain AMM Program:
- Deployed through Anchor (as evidenced by Anchor.toml and build/deploy commands).
- Contains two major subdivisions:
▪ Administrative and operational instructions (in “programs/amm/src/instructions/admin” and root “instructions”).
▪ Business logic libraries and utility functions (in “programs/amm/src/libraries” and “programs/amm/src/util”).
- Represents the smart contract’s logic for liquidity provision, swaps, and fee management.
- Solana Blockchain Environment:
- Represents the underlying blockchain network that hosts the deployed on-chain program.
- Handles proof-of-stake consensus, transaction processing, and state management.
- External Integration (CPI):
- A reference to the Raydium CPI example indicates that the program can be called by other programs for cross-program invocations. This should be marked as integration points with external systems.

##### Relationships & Interactions
- The Client Application sends transaction instructions (calls to the program’s methods) to the Solana network.
- Once deployed, the on-chain AMM program processes incoming user and administrative instructions, interacts with its internal state modules (for pool states, positions, etc.), and performs calculations via its library modules.

##### Architectural Patterns & Key Technologies
- Separation of Concerns: Clear split between off-chain client code and on-chain program logic.
- Modular Design: Distinct organization of instructions, libraries, states, and utilities within the AMM program.
- Use of Rust and the Anchor framework for Solana, leveraging Rust’s strong type system and performance.
- CPI (Cross-Program Invocation) design pattern for enabling interoperability between on-chain programs.

##### Elements
- Clear labels for each major component: "Client Application", "AMM On-chain Program", "Core Libraries", "State Modules", and "Solana Blockchain".
- Annotations: Add brief notes to highlight important design patterns (like CPI) or key responsibilities such as "Liquidity Math" or "Swap Execution".

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Off-chain Components"
        Client["Client Application\n(Instruction Builder & RPC Communication)"]:::frontend
    end

    subgraph "On-chain AMM Program"
        subgraph "Instruction Handlers"
            UserInstr["User Instructions"]:::backend
            AdminInstr["Admin Instructions"]:::backend
        end
        Libraries["Core Libraries\n(Business Logic & Math)"]:::backend
        States["State Management\n(Data Structures)"]:::backend
        Utilities["Utility Modules\n(Account Loading & Token Interactions)"]:::backend
    end

    subgraph "Blockchain Environment"
        Solana[/"Solana Blockchain"/]:::database
    end

    subgraph "External Integration"
        External["External Systems\n(CPI Invocation)"]:::external
    end

    Client -->|"submits_transactions"| Solana
    Solana -->|"executes"| UserInstr
    Solana -->|"executes"| AdminInstr
    Solana -->|"utilizes"| Libraries
    Solana -->|"updates"| States
    Solana -->|"calls"| Utilities
    External -->|"invokes_CPI_on"| UserInstr

    UserInstr --> Libraries
    Libraries --> States
    States --> Utilities

    click Client "https://github.com/raydium-io/raydium-clmm/tree/master/client/"
    click UserInstr "https://github.com/raydium-io/raydium-clmm/tree/master/programs/amm/src/instructions/"
    click AdminInstr "https://github.com/raydium-io/raydium-clmm/tree/master/programs/amm/src/instructions/admin/"
    click Libraries "https://github.com/raydium-io/raydium-clmm/tree/master/programs/amm/src/libraries/"
    click States "https://github.com/raydium-io/raydium-clmm/tree/master/programs/amm/src/states/"
    click Utilities "https://github.com/raydium-io/raydium-clmm/tree/master/programs/amm/src/util/"

    classDef frontend fill:#C6E2FF,stroke:#333,stroke-width:2px;
    classDef backend fill:#FAD6A5,stroke:#333,stroke-width:2px;
    classDef database fill:#F4A460,stroke:#333,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#333,stroke-width:2px;
```
