# mrgnlabs/marginfi-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/mrgnlabs/marginfi-v2
- Repository: https://github.com/mrgnlabs/marginfi-v2

## Overview

##### Main Components to Highlight
- On-Chain Programs: Indicate the various Solana programs such as the core marginfi program, liquidity incentive program, mocks, and test transfer hooks. (These are in the “programs/…” directory and are built with Anchor and Cargo.)
- Marginfi Group & Lending Pool: Represent the marginfi group as a central component that manages lending pools. Within these pools, you have multiple banks (each with its own mint and oracle configuration).
- Banks & Oracles: For each bank, show its relationship with its custom oracle (currently Pyth, with plans for Switchboard). This communicates the external data dependency that feeds into the risk engine.
- Marginfi Accounts and Users (Signers): Illustrate that users (signers) interact with the system via marginfi accounts, which allow multiple asset interactions.
- Client Interfaces and Tools: Include supporting components such as the command-line client in “clients/rust/marginfi-cli”, automated tests (both Rust and TS tests in “tests/…”), and deployment/observability tooling (in “observability”, “scripts”, “tools”).

##### Relationships & Interactions
- For each Bank, include a bidirectional relationship with a Price Oracle since banks use real-time price feeds (Pyth) to determine LTVs and risk.
- Risk engine monitoring data flows from user accounts and banks to the risk-management logic, with possible feedback loops (e.g., triggering liquidations).

##### Architectural Patterns and Technologies
- Modular and layered structure: on-chain programs for the business logic, client libraries (Rust CLI), and observability modules (indexer, ETL in Python and Rust).
- Use the microservices or modular components concept since many directories indicate separate concerns, such as “programs”, “observability”, “clients”, and “tools”.
- Mention use of Anchor (as observed in Anchor.toml, tests, and deployment docs) for program development.
- Testing framework structure and CI/CD tooling (GitHub actions, workflow YAMLs) that streamline build, deploy, and verification processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Protocol Components
    User["User/Signer"]:::user
    AccMgmt["Marginfi Account Management"]:::protocol
    GroupLogic["Marginfi Group Logic"]:::protocol
    LendingPool["Lending Pool"]:::protocol
    Banks["Bank & Oracle Configurations"]:::protocol
    RiskEngine["Risk Engine"]:::protocol

    %% On-Chain Programs
    CoreProgram["Marginfi Core Program"]:::onchain
    LiquidityProgram["Liquidity Incentive Program"]:::onchain
    Mocks["Mocks Program"]:::onchain
    TestTransfer["Test Transfer Hook"]:::onchain

    %% Off-Chain & Tools
    CLI["Marginfi CLI"]:::offchain
    CLIOracle["CLI Oracle Processor"]:::offchain
    AutoTests["Automated Tests"]:::offchain
    ObsETL["Observability ETL"]:::offchain
    ObsIndexer["Observability Indexer"]:::offchain
    DeployScripts["Deployment Scripts"]:::offchain

    %% Protocol Flow
    User -->|"initiates"| AccMgmt
    AccMgmt -->|"manages"| GroupLogic
    GroupLogic -->|"controls"| LendingPool
    LendingPool -->|"routes to"| Banks
    AccMgmt -->|"monitored by"| RiskEngine
    Banks <-->|"feeds data"| RiskEngine

    %% On-Chain Interactions
    CLI -->|"invokes"| CoreProgram
    CoreProgram -->|"updates"| GroupLogic
    LiquidityProgram -->|"supports"| LendingPool
    Mocks -->|"simulates"| CoreProgram
    TestTransfer -->|"triggers"| CoreProgram

    %% Off-Chain Interactions
    CLIOracle -->|"fetches prices from"| Banks
    DeployScripts -->|"deploys"| CLI
    CoreProgram -->|"logs"| ObsETL
    CoreProgram -->|"logs"| ObsIndexer
    AutoTests -->|"tests system"| GroupLogic

    %% Class Definitions for Colors
    classDef onchain fill:#a7d8ff,stroke:#0a5,stroke-width:2px;
    classDef protocol fill:#d5f5e3,stroke:#1f7,stroke-width:2px;
    classDef offchain fill:#ffe699,stroke:#c76,stroke-width:2px;
    classDef user fill:#ffb3b3,stroke:#a33,stroke-width:2px;

    %% Click Events
    click CoreProgram "https://github.com/mrgnlabs/marginfi-v2/tree/main/programs/marginfi"
    click LiquidityProgram "https://github.com/mrgnlabs/marginfi-v2/tree/main/programs/liquidity-incentive-program"
    click Mocks "https://github.com/mrgnlabs/marginfi-v2/tree/main/programs/mocks"
    click TestTransfer "https://github.com/mrgnlabs/marginfi-v2/tree/main/programs/test_transfer_hook"

    click GroupLogic "https://github.com/mrgnlabs/marginfi-v2/tree/main/programs/marginfi/src/instructions/marginfi_group"
    click GroupLogic "https://github.com/mrgnlabs/marginfi-v2/blob/main/programs/marginfi/src/state/marginfi_group.rs"

    click Banks "https://github.com/mrgnlabs/marginfi-v2/blob/main/programs/marginfi/src/state/price.rs"
    click Banks "https://github.com/mrgnlabs/marginfi-v2/blob/main/test-utils/src/bank.rs"

    click AccMgmt "https://github.com/mrgnlabs/marginfi-v2/blob/main/programs/marginfi/src/state/marginfi_account.rs"
    click CLIOracle "https://github.com/mrgnlabs/marginfi-v2/blob/main/clients/rust/marginfi-cli/src/processor/oracle.rs"
    click CLI "https://github.com/mrgnlabs/marginfi-v2/tree/main/clients/rust/marginfi-cli"
    click AutoTests "https://github.com/mrgnlabs/marginfi-v2/tree/main/tests/"
    click ObsETL "https://github.com/mrgnlabs/marginfi-v2/tree/main/observability/etl"
    click ObsIndexer "https://github.com/mrgnlabs/marginfi-v2/tree/main/observability/indexer"
    click DeployScripts "https://github.com/mrgnlabs/marginfi-v2/tree/main/scripts/"
```
