# aarna-ai/atv-ethereum architecture

> Architecture diagram of the GitHub repository aarna-ai/atv-ethereum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aarna-ai/atv-ethereum
- Repository: https://github.com/aarna-ai/atv-ethereum

## Overview

##### Project type and purpose
- This is an Ethereum smart‐contract project using Hardhat (and Truffle for coverage) focused on testing a modular DeFi protocol (“AFi”) and its integration with on‐chain services (like 1inch, oracles).
- Purpose: define, compile, deploy, and test a set of core contracts + mocks, run them against a mainnet fork, measure coverage, and validate behaviors.

##### File structure
- Top‐level:
- contracts/ – main Solidity source
- contracts/mockcontracts/ – supporting mock contracts for isolated/unit tests
- test/ – JS/TS test suites organized by module (Migration, OneInch, core AFi modules)
- hardhat.config.js & truffle-config.js – compilation/deployment settings
- utils/ – helper scripts/constants for tests
- coverage/ – generated HTML/JSON reports
- Inside contracts/:
- /Interfaces – external protocol & internal interface definitions (e.g., IFactory, IRouter)
- /Libraries – shared on‐chain libraries (e.g., SafeMath, Address)
- /mockcontracts – mirror of structure under contracts/, containing mock implementations of Interfaces & Libraries for testing
- Configuration files indicate use of Hardhat (forking mainnet) and solidity‐coverage.

##### Key README insights
- Mainnet fork via Infura/Blast endpoint
- Hardhat commands to compile, test, and generate coverage
- Emphasis on keeping the node running while coverage commands execute

##### Main components
a. On-Chain Contracts Layer
- Core AFi Contracts
- AFiFactory
- AFiManager
- AFiBase
- AFiExchangeMock / AFiOracle
- AFiPassiveRebal / time-delay modules
- Utility contracts (Vaults, Token interfaces)
- Interfaces & Libraries
- External (IERC20, IOneInchRouter)
- Internal (IManager, ILibrary functions)
- MockContracts (under contracts/mockcontracts)
- Mocks for oracles, exchange, ERC20 tokens
b. Off-Chain Tooling Layer
- Hardhat Node (mainnet fork)
- Test runner (Mocha/Chai scripts in test/)
- Coverage tools (solidity-coverage, Truffle coverage plugin)
- Utils (constants, payload builders, USDT mainnet address)
c. External Services
- Ethereum Mainnet (via Infura/Blast RPC)
- 1Inch API/Router (for swap integration tests)
- Oracle price feeds

##### Relationships & Interactions
- Deployment flow: Hardhat → deploy core contracts → link libraries → instantiate factory/manager
- Core contracts interact: Factory creates Base vaults; Manager triggers rebalances via Exchange/Oracle
- Off-chain tests invoke contract functions through Hardhat, simulate time (ForwardTimeScript), measure outcomes
- Mock contracts emulate oracles/ERC20 to isolate unit tests
- Coverage plugin instruments contracts under test, collects execution data

##### Architectural patterns & design principles
- Modular design: Factory/Manager/Base separation
- Pluggable modules: Oracle, Exchange, Rebalance logic loaded at runtime
- Use of Interfaces and Libraries to decouple implementation
- Mocks to achieve test isolation
- Forked environment to blend unit tests with mainnet data

##### Hierarchy inside contracts/
1. Interfaces (Interfaces/)
2. Libraries (Libraries/)
3. Core contracts & modules
- Next to it, a mirrored “contracts/mockcontracts/” container with its own Interfaces/ and Libraries/ subfolders and mock modules
- Mock Interface/Library to its real counterpart to show one-to-one substitution in tests

##### Detail but avoid over-fragmentation
- Related contracts where logical (e.g., all Rebalance modules in one cluster)
- Still show each contract’s name for traceability back to the file tree
- Essential flows: deployment, function calls, test invocation, coverage instrumentation

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "contracts/"
        direction TB
        intfMain["contracts/Interfaces/"]
        libMain["contracts/Libraries/"]
        subgraph "Core Contracts & Modules"
            direction TB
            AFiFactory["AFiFactory.sol"]:::core
            AFiManager["AFiManager.sol"]:::core
            AFiBase["AFiBase.sol"]:::core
            AFiExchangeMock["AFiExchangeMock.sol"]:::core
            AFiOracle["AFiOracle.sol"]:::core
            AFiPassiveRebal["AFiPassiveRebal.sol"]:::core
            AFiTimeDelay["AFiTimeDelayModule.sol"]:::core
        end
    end

    subgraph "contracts/mockcontracts/contracts/"
        direction TB
        intfMock["contracts/mockcontracts/contracts/Interfaces/"]:::mock
        libMock["contracts/mockcontracts/contracts/Libraries/"]:::mock
        subgraph "Mock Core Modules"
            direction TB
            mockModules["contracts/mockcontracts/contracts/mockcontracts/"]:::mock
        end
    end

    %% Relationships between real and mock
    intfMock -.-> intfMain
    libMock -.-> libMain
    mockModules -.-> AFiFactory
    mockModules -.-> AFiManager
    mockModules -.-> AFiBase

    %% Click events
    click AFiFactory "https://github.com/aarna-ai/atv-ethereum/blob/main/contracts/AFiFactory.sol"
    click AFiManager "https://github.com/aarna-ai/atv-ethereum/blob/main/contracts/AFiManager.sol"
    click AFiBase "https://github.com/aarna-ai/atv-ethereum/blob/main/contracts/AFiBase.sol"
    click AFiExchangeMock "https://github.com/aarna-ai/atv-ethereum/blob/main/contracts/AFiExchangeMock.sol"
    click AFiOracle "https://github.com/aarna-ai/atv-ethereum/blob/main/contracts/AFiOracle.sol"
    click AFiPassiveRebal "https://github.com/aarna-ai/atv-ethereum/blob/main/contracts/AFiPassiveRebal.sol"
    click AFiTimeDelay "https://github.com/aarna-ai/atv-ethereum/blob/main/contracts/AFiTimeDelayModule.sol"
    click intfMain "https://github.com/aarna-ai/atv-ethereum/tree/main/contracts/Interfaces/"
    click libMain "https://github.com/aarna-ai/atv-ethereum/tree/main/contracts/Libraries/"
    click intfMock "https://github.com/aarna-ai/atv-ethereum/tree/main/contracts/mockcontracts/contracts/Interfaces/"
    click libMock "https://github.com/aarna-ai/atv-ethereum/tree/main/contracts/mockcontracts/contracts/Libraries/"
    click mockModules "https://github.com/aarna-ai/atv-ethereum/tree/main/contracts/mockcontracts/contracts/mockcontracts/"

    classDef core fill:#cce5ff,stroke:#004085,color:#000;
    classDef mock fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef folder fill:#d4edda,stroke:#155724,color:#000;
```
