# morpho-org/morpho-blue architecture

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

- Interactive diagram: https://gitdiagram.com/morpho-org/morpho-blue
- Repository: https://github.com/morpho-org/morpho-blue

## Overview

##### Main Components
- Core Contract: The heart of the protocol is in src/Morpho.sol, which encompasses the business logic for lending.
- Internal Libraries: Found in src/libraries, these provide essential functions; note that the subdirectory src/libraries/periphery includes helper libraries for integrators.
- Interfaces: In src/interfaces, these specify the contracts’ API, such as IMorpho.sol, which lists important market dependency requirements.
- Mock Contracts: The src/mocks directory isolates test contracts used to simulate external behaviors during testing.
- Testing Frameworks: There are separate test suites for Forge (via test/forge) and Hardhat (via test/hardhat), reflecting diverse testing strategies.
- Formal Verification: The certora folder contains configurations and specifications (conf and specs directories) for running formal verification; it helps ensure properties like reentrancy-safety, accurate math, correct state, and more.
- Audits and Documentation: The audits folder and the whitepaper (morpho-blue-whitepaper.pdf) provide external validation and detailed protocol descriptions.
- CI/CD Pipelines: The .github/workflows folder with multiple YAML files (e.g., foundry.yml, hardhat.yml, halmos.yml) shows automated testing, formatting, and release processes. Other configuration files such as foundry.toml, tsconfig.json, and hardhat.config.ts also coordinate build and deployment setups.

##### Relationships and Interactions
- Core Contract to its test environments (forge and Hardhat tests) to indicate how the code is verified via both simulation (mock contracts) and formal proofs (Certora specifications).
- CI/CD workflows as a side component that continuously integrates and tests the codebase.
- Tie in the audits and whitepaper as external validation and documentation sources.
- That the protocol is designed to be augmentable (through periphery libraries) and to interact with external financial primitives (flash loans, oracles).

##### Architectural Patterns and Design Principles
- Modular design: separate concerns in core logic, reusable libraries, mock/test contracts, and formal verification specs.
- Separation of environments: production contracts vs. testing (Forge and Hardhat) vs. verification tools, which ensures robust development via multiple layers of quality assurance.
- CI/CD integration: automated workflows based on GitHub Actions ensure quality and standardized deployment.

##### Technology, Frameworks, and Tools
- Solidity for smart contract development.
- Foundry and Hardhat for testing frameworks.
- Certora formal verification tools as evidenced by the certora folder.
- GitHub Actions for automated testing, formatting, and releases.
- Dependency management via package.json and Yarn (as indicated through installation instructions).

##### Specific Elements
- Each major directory’s purpose should be represented (e.g., “src” for contracts and libraries, “test” for test suites, “certora” for verification).
- Visual markers to denote components that are external to the logic (like audits and whitepaper documentation) along with CI/CD workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Core["Morpho.sol (Core Contract)"]:::contract

    subgraph "Internal Libraries"
        LIB["Internal Libraries"]:::library
        PERI["Periphery Libraries"]:::library
    end

    Interfaces["Interfaces"]:::interface

    subgraph "Mock Contracts"
        MOCKS["Mock Contracts"]:::mock
        MOCKS_INT["Mock Interfaces"]:::mock
    end

    subgraph "Testing Frameworks"
        FORGE["Forge Tests"]:::testing
        HARDHAT["Hardhat Tests"]:::testing
        HSpec["Morpho.spec.ts"]:::testing
    end

    VERIFY["Certora Verification"]:::verification
    CICD["CI/CD Pipelines"]:::cicd

    subgraph "Audits & Documentation"
        AUDITS["Audits"]:::doc
        WHITEPAPER["Whitepaper"]:::doc
    end

    EX["External Integrations (Oracles,Flash Loans)"]:::external

    %% Connections from Core Contract to Supporting Components
    Core -->|"calls"| LIB
    Core -->|"calls"| PERI
    Core -->|"implements"| Interfaces
    Core -->|"uses_mocks"| MOCKS
    Core -->|"uses_mocks"| MOCKS_INT
    Core -->|"tested_by"| FORGE
    Core -->|"tested_by"| HARDHAT
    HARDHAT -->|"includes"| HSpec
    Core -->|"verified_by"| VERIFY
    Core -->|"integrated_in"| CICD
    Core -->|"audited_by"| AUDITS
    Core -->|"documented_in"| WHITEPAPER
    Core -->|"integrates_with"| EX

    %% Click Events
    click Core "https://github.com/morpho-org/morpho-blue/blob/main/src/Morpho.sol"
    click LIB "https://github.com/morpho-org/morpho-blue/tree/main/src/libraries"
    click PERI "https://github.com/morpho-org/morpho-blue/tree/main/src/libraries/periphery"
    click Interfaces "https://github.com/morpho-org/morpho-blue/tree/main/src/interfaces"
    click MOCKS "https://github.com/morpho-org/morpho-blue/tree/main/src/mocks"
    click MOCKS_INT "https://github.com/morpho-org/morpho-blue/tree/main/src/mocks/interfaces"
    click FORGE "https://github.com/morpho-org/morpho-blue/tree/main/test/forge"
    click HARDHAT "https://github.com/morpho-org/morpho-blue/tree/main/test/hardhat"
    click HSpec "https://github.com/morpho-org/morpho-blue/blob/main/test/hardhat/Morpho.spec.ts"
    click VERIFY "https://github.com/morpho-org/morpho-blue/tree/main/certora"
    click CICD "https://github.com/morpho-org/morpho-blue/tree/main/.github/workflows"
    click AUDITS "https://github.com/morpho-org/morpho-blue/tree/main/audits"
    click WHITEPAPER "https://github.com/morpho-org/morpho-blue/blob/main/morpho-blue-whitepaper.pdf"

    %% Style Definitions
    classDef contract fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef library fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef interface fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef mock fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef testing fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef verification fill:#F5EEF8,stroke:#8E44AD,stroke-width:2px;
    classDef cicd fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef doc fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#D5D8DC,stroke:#566573,stroke-width:2px;
```
