# gmsol-labs/gmx-solana architecture

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

- Interactive diagram: https://gitdiagram.com/gmsol-labs/gmx-solana
- Repository: https://github.com/gmsol-labs/gmx-solana

## Overview

##### Main components
- On-Chain Programs: Under the directories “programs” (gmsol-store, gmsol-treasury, gmsol-timelock) and “crates/programs”. These smart contracts represent the core logic handling state changes, deposits, withdrawals, oracle interactions, and role-based permission operations.
- Domain Logic & Models: The “crates/gmsol-model” and associated actions (deposit, withdraw, order, swap etc.) encapsulate the business logic for managing trading activities, market states, pooling, and position management.
- Utility Libraries: Components such as “crates/gmsol-utils”, “crates/solana-utils”, and “crates/gmsol-decode” provide value conversions, token & pricing utilities, data decoding for on-chain data structures, and integration with oracles (Chainlink, Pyth, Switchboard).
- External Interfaces & SDK: The “crates/sdk” exposes a JavaScript/TypeScript interface along with CLI examples and tests, which external applications or developer tools can use to interact with the on-chain programs.
- Configurations & IDLs: The config files (in “config”) and the IDL files (as described in the README under “idls”) are essential for specifying parameters used by both on-chain programs and client integrations.
- Testing & Integration: Multiple “tests” directories under various crates indicate unit tests as well as integration tests (including those related to Anchor) to ensure robustness, as well as scripts for localnet testing.

##### Relationships and interactions
- The on-chain programs (gmsol-store, gmsol-treasury, and gmsol-timelock) reside directly on the Solana blockchain and interact with each other, with a clear separation of concerns (storing state, treasury operations, and timelock governance).
- The domain logic libraries (gmsol-model) serve as a backbone for business logic that the programs rely on to process actions such as deposits, withdrawals, collateral calculations, and interaction with external oracles.
- Oracle integration is achieved via dedicated modules (e.g., chainlink-datastreams, pyth-related code in gmsol and switchboard modules) that source market and price data from external services.
- The SDK and CLI (in “crates/sdk” and “crates/gmsol”) provide high-level abstractions and user interfaces to interact with the on-chain programs via generated IDLs and Anchor’s “declare_program!” mechanism.
- Configuration files define environment-specific or market-specific details that are used across programs and tests.

##### Architectural patterns and technologies
- Modular Architecture: The project uses a micro-crate approach, with each logical unit (model, decode, util, program) being encapsulated in its own crate. This enforces separation of concerns.
- On-Chain Smart Contract Patterns: Use of Anchor as the framework for writing Solana programs ensures an easy-to-use abstraction over low-level Solana APIs.
- Testing & Integration Focus: Numerous tests and integration test directories underscore the emphasis on rigorous testing in deployment pipelines.
- Dependency Injection & Configuration Management: With separate configuration files and IDLs maintained for programs, the design supports easy updates and replicable deployments.
- External Service Integration: The project integrates with external oracle services (Chainlink, Pyth, Switchboard), which is captured by separate modules and external program integrations.

##### Summary
a. Core On-Chain Programs:
– gmsol-store, gmsol-treasury, gmsol-timelock
– Relationships: They interact with each other and with external state sources and oracles.
b. Domain & Business Logic:
– gmsol-model: actions, market, pool, position, and event handling.
c. Utility and Service Integrations:
– gmsol-decode (for parsing on-chain data)
– gmsol-utils, solana-utils (for common functions, fixed number handling, RPC, transaction building)
– Oracle modules: Chainlink, Pyth, Switchboard.
d. External Interface Layer:
– SDK & CLI for developers, along with example applications.
– IDL management for exposing program APIs.
e. Configuration & Testing:
– Config directories, integration test scripts, and local cluster setups.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    subgraph "External Interfaces"
        SDK["SDK & CLI"]:::external
    end

    %% Configurations & IDLs
    subgraph "Configurations & IDLs"
        CF["Config Files"]:::config
        IDL["IDL Files"]:::config
    end

    %% Domain Logic & Models
    subgraph "Domain Logic & Models"
        DM["Domain Model (gmsol-model)"]:::domain
    end

    %% Utility & Integration Libraries
    subgraph "Utility & Integration Libraries"
        GD["gmsol-decode Library"]:::utility
        GU["gmsol-utils Library"]:::utility
        SU["solana-utils Library"]:::utility
        CL["Chainlink Oracle Module"]:::oracle
    end

    %% On-Chain Programs
    subgraph "On-Chain Programs"
        GS["gmsol-store Program"]:::onchain
        GT["gmsol-treasury Program"]:::onchain
        TL["gmsol-timelock Program"]:::onchain
    end

    %% Relationships: External Interfaces to On-Chain Programs
    SDK -->|"calls"| GS
    SDK -->|"calls"| GT
    SDK -->|"calls"| TL

    %% Relationships: Configurations & IDLs to On-Chain Programs
    CF -->|"configures"| GS
    CF -->|"configures"| GT
    CF -->|"configures"| TL
    IDL -->|"defines"| GS
    IDL -->|"defines"| GT
    IDL -->|"defines"| TL

    %% Relationships: Domain Logic to On-Chain Programs
    DM -->|"supports"| GS
    DM -->|"supports"| GT
    DM -->|"supports"| TL
    SDK -->|"integrates_with"| DM

    %% Relationships: Utility Libraries to On-Chain Programs
    GD -->|"decodes_data_for"| GS
    GD -->|"decodes_data_for"| GT
    GD -->|"decodes_data_for"| TL

    GU -->|"provides_utilities_to"| GS
    GU -->|"provides_utilities_to"| GT
    GU -->|"provides_utilities_to"| TL

    SU -->|"RPC_&_tx_building_for"| GS
    SU -->|"RPC_&_tx_building_for"| GT
    SU -->|"RPC_&_tx_building_for"| TL

    %% Relationships: Oracle Integration to On-Chain Programs
    CL -->|"feeds_oracle_data_to"| GS
    CL -->|"feeds_oracle_data_to"| GT
    CL -->|"feeds_oracle_data_to"| TL

    %% Class Definitions for styling
    classDef external fill:#b3cde0,stroke:#1f77b4,stroke-width:2px;
    classDef config fill:#fff2cc,stroke:#b8860b,stroke-width:2px;
    classDef domain fill:#ccebc5,stroke:#228B22,stroke-width:2px;
    classDef utility fill:#decce4,stroke:#8a2be2,stroke-width:2px;
    classDef oracle fill:#fde2e4,stroke:#d23669,stroke-width:2px;
    classDef onchain fill:#ffcccb,stroke:#ff6347,stroke-width:2px;

    %% Click Events
    click GS "https://github.com/gmsol-labs/gmx-solana/tree/main/programs/gmsol-store"
    click GT "https://github.com/gmsol-labs/gmx-solana/tree/main/programs/gmsol-treasury"
    click TL "https://github.com/gmsol-labs/gmx-solana/tree/main/programs/gmsol-timelock"
    click DM "https://github.com/gmsol-labs/gmx-solana/tree/main/crates/gmsol-model"
    click GD "https://github.com/gmsol-labs/gmx-solana/tree/main/crates/gmsol-decode"
    click GU "https://github.com/gmsol-labs/gmx-solana/tree/main/crates/gmsol-utils"
    click SU "https://github.com/gmsol-labs/gmx-solana/tree/main/crates/solana-utils"
    click CL "https://github.com/gmsol-labs/gmx-solana/tree/main/crates/chainlink-datastreams"
    click SDK "https://github.com/gmsol-labs/gmx-solana/tree/main/crates/sdk"
    click CF "https://github.com/gmsol-labs/gmx-solana/tree/main/config"
    click IDL "https://github.com/gmsol-labs/gmx-solana/tree/main/crates/programs/idls"
```
