# aave/aave-v3-core architecture

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

- Interactive diagram: https://gitdiagram.com/aave/aave-v3-core
- Repository: https://github.com/aave/aave-v3-core

## Overview

##### Main Components
- Protocol: Contains the business logic for the lending pool, configuration, and management (see “contracts/protocol” with its libraries, pool, tokenization, etc.).
- Flashloan Modules: Found under “contracts/flashloan,” which implement the flashloan base contracts and related interfaces.
- Interfaces & Mocks: In “contracts/interfaces” and “contracts/mocks.” These represent the standardized interfaces for interacting with the protocol as well as test harness components.
- Dependencies: External libraries from Chainlink, Gnosis, OpenZeppelin are located in “contracts/dependencies.” These bring in audited, battle-tested code and upgradeability patterns.

- CI/CD and Audit/Verification Artifacts – The repository includes GitHub workflows (inside “.github/workflows”) and linting/configuration files. It also contains a collection of audit reports and formal verification documents (under “audits” and “certora”). Show these external quality and security controls as a separate but connected module, highlighting interactions with the core contracts.

- External Dependencies and Consumer Layers – Though primarily a core smart contract protocol, note how external developers interact with the system. For instance, users can install the NPM package (“@aave/core-v3”), use the JSON artifact outputs from the “artifacts/” folder, and connect through the developer documentation. Include these as “Consumer Applications” or “External Integrators” interacting with the protocols via APIs.

##### Relationships and Interactions
- The Development Environment (Docker Compose + Hardhat) compiles and deploys the smart contracts.
- Testing Suites (in “test-suites” and “helpers”) interact with the deployed contracts, simulating various protocol functionalities (like supply, borrowing, flashloans, and liquidation flows).
- The smart contracts rely on external dependencies (the libraries under “contracts/dependencies”) for secure implementations of upgradeability, oracles, etc.
- Consumers (either through direct NPM installation or via provided interfaces in the contracts) access protocol capabilities.

##### Architectural Patterns and Design Principles
- Modular Design: Each subdirectory under “contracts” represents a separate module (protocol, flashloan, configuration, mocks, etc.), emphasizing separation of concerns.
- Testing-Driven Development: The robust “test-suites” directory indicates an architecture that emphasizes thorough integration and unit testing.
- Containerization of the Build Environment: Docker and associated environment setups demonstrate modern DevOps practices for reproducible deployments and testing.

##### Relevant Technologies and Tools
- Docker & Docker Compose (for containerized environments)
- Hardhat (for Solidity compilation, testing, and deployment)
- Solidity (smart contract language)
- External libraries: OpenZeppelin, Chainlink, Gnosis, etc.
- CI/CD tools: GitHub workflows, GitLab CI (see .gitlab-ci.yml), and Husky for pre-commit hooks.
- Formal Verification: Certora’s toolchain and audit reports.

##### Final Steps
- Sketch the high-level interconnected components first (Smart Contracts, Environment/Testing, CI & Audits, and External Consumers).
- Drill down into the smart contract section to show its submodules (e.g., “pool”, “flashloan”, “interfaces”).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Development Environment
    DE["Development Environment (Docker, Hardhat, Helpers)"]:::dev

    %% Smart Contracts Layer
    subgraph "Smart Contracts"
        CC["Core Contracts"]:::contract
        PM["Protocol Module"]:::contract
        FL["Flashloan Modules"]:::contract
        IM["Interfaces & Mocks"]:::contract
        DEP["Dependencies (External Libraries)"]:::contract
    end

    %% Quality & Testing Layer
    TS["Testing Suites"]:::test
    CD["CI/CD Pipelines"]:::ci
    AR["Audit Reports"]:::audit
    FV["Formal Verification"]:::audit

    %% External Consumers Layer
    EC["External Consumers (NPM Package & Artifacts)"]:::external

    %% Connections between layers
    DE -->|"compiles&deploys"| CC
    TS -->|"tests&interacts"| CC
    CD -->|"runs-pipelines"| CC
    AR -->|"audits"| CC
    FV -->|"verifies"| CC
    EC -->|"accesses"| CC

    %% Internal Smart Contracts relationships
    CC -->|"includes"| PM
    CC -->|"includes"| FL
    CC -->|"includes"| IM
    CC -->|"includes"| DEP

    %% CI/CD triggering audit and verification
    CD -->|"triggers"| AR
    CD -->|"triggers"| FV

    %% Click Events for components
    click CC "https://github.com/aave/aave-v3-core/tree/master/contracts"
    click PM "https://github.com/aave/aave-v3-core/tree/master/contracts/protocol"
    click FL "https://github.com/aave/aave-v3-core/tree/master/contracts/flashloan"
    click IM "https://github.com/aave/aave-v3-core/tree/master/contracts/interfaces"
    click IM "https://github.com/aave/aave-v3-core/tree/master/contracts/mocks"
    click DEP "https://github.com/aave/aave-v3-core/tree/master/contracts/dependencies"
    click DE "https://github.com/aave/aave-v3-core/tree/master/Dockerfile"
    click DE "https://github.com/aave/aave-v3-core/blob/master/docker-compose.yml"
    click DE "https://github.com/aave/aave-v3-core/blob/master/hardhat.config.ts"
    click DE "https://github.com/aave/aave-v3-core/tree/master/helpers"
    click TS "https://github.com/aave/aave-v3-core/tree/master/test-suites"
    click CD "https://github.com/aave/aave-v3-core/tree/master/.github/workflows"
    click CD "https://github.com/aave/aave-v3-core/blob/master/.gitlab-ci.yml"
    click AR "https://github.com/aave/aave-v3-core/tree/master/audits"
    click FV "https://github.com/aave/aave-v3-core/tree/master/certora"
    click EC "https://github.com/aave/aave-v3-core/blob/master/package.json"
    click EC "https://github.com/aave/aave-v3-core/blob/master/README.md"

    %% Styles for each layer
    classDef dev fill:#e1f5fe,stroke:#0288d1,stroke-width:2px;
    classDef contract fill:#e8f5e9,stroke:#388e3c,stroke-width:2px;
    classDef test fill:#fff3e0,stroke:#f57c00,stroke-width:2px;
    classDef ci fill:#fce4ec,stroke:#d81b60,stroke-width:2px;
    classDef audit fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
    classDef external fill:#ffebee,stroke:#c62828,stroke-width:2px;
```
