# hai-on-op/core architecture

> Architecture diagram of the GitHub repository hai-on-op/core, 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/hai-on-op/core
- Repository: https://github.com/hai-on-op/core

## Overview

##### Main Components
- Core Smart Contracts: Include the directories under src/contracts – for instance, contracts related to governance, tokens, oracles, proxies (and proxy actions), settlement, and utilities.
- Factories & Interfaces: There is a “factories” sub-directory (both under contracts and interfaces) which indicates the use of the factory pattern for creating contract instances dynamically.
- Modules: In the docs you see detailed sections on auctions, modules (like liq_engine, oracle_relayer, pid_controller, safe_engine, sf_treasury, tax_collector) – these should be highlighted as key modular components of the system.
- Proxies and Action Management: Under src/contracts/proxies (with actions, hai_proxy, hai_proxy_factory, etc.) you have a well-developed proxy mechanism suggesting a separation between core logic and upgradeability or protocol management.
- Testing Suite: Although not part of the runtime architecture, the test directories (unit tests, simulation tests including PID controllers, and e2e tests) verify how these components interact.

##### Relationships and Interactions
- Interconnections between modules – for instance, how the pid_controller in the simulations interacts with auction modules or settlement modules.
- If applicable, map out interactions such as governance decisions triggering executable contracts, token issuance affecting settlement mechanisms, and oracle data updates influencing modules like the oracle_relayer.

##### Architectural Patterns and Design Principles
- Modularity: The project is highly modular – each contract group (governance, tokens, proxies, settlement) represents individual components that communicate with each other.
- Separation of Concerns: By dividing code into specific directories (contracts, interfaces, libraries, and tests), the architecture reinforces a separation between contract implementations, their external interfaces, and testing.
- Factory Pattern: The clear “factories” directories indicate dynamic instantiation – show that factories are responsible for creating contract instances.
- Proxy Pattern: With proxies and proxy actions as separate components, indicate that upgradeability or indirection control is a core design principle.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Interface Layer
    subgraph "Client / External Interface Layer"
        EI("External Interfaces"):::interface
    end

    %% Core Contract Layer
    subgraph "Core Contract Layer"
        Gov("Governance Contracts"):::coreGovernance
        Tok("Token Contracts"):::coreToken
        Sett("Settlement Module"):::coreSettlement
        Util("Utility Libraries"):::coreUtils
        subgraph "Proxy Contracts"
            PM("Proxy Main"):::coreProxy
            PA("Proxy Actions"):::coreProxy
        end
    end

    %% Factory & Proxy Mechanisms Layer
    subgraph "Factory & Proxy Mechanisms Layer"
        CF("Contract Factories"):::factory
        IF("Interface Factories"):::factory
    end

    %% Modules Layer
    subgraph "Modules Layer"
        AU("Auctions Module"):::module
        SM("System Modules"):::module
        PMd("Proxy Modules"):::module
    end

    %% Supporting Infrastructure Layer
    subgraph "Supporting Infrastructure Layer"
        TS("Testing Suite"):::infra
        DC("Deployment/CI"):::infra
        FC("Foundry Config"):::infra
        Doc("Documentation"):::infra
    end

    %% Connections between Layers and Components
    CF -->|"creates"| Gov
    CF -->|"creates"| Tok
    CF -->|"creates"| PM
    IF -->|"creates"| EI
    EI -->|"calls"| Gov
    EI -->|"calls"| Tok
    EI -->|"calls"| Sett
    EI -->|"calls"| Util
    Gov -->|"triggers"| Sett
    Tok -->|"affects"| Sett
    PM -->|"delegatesTo"| Gov
    AU -->|"interactsWith"| Sett
    SM -->|"supports"| Sett
    PMd -->|"enhances"| PM
    DC --> FC
    DC --> TS
    Doc --> AU
    Doc --> SM
    Doc --> PMd

    %% Click Events
    click Gov "https://github.com/hai-on-op/core/tree/main/src/contracts/governance"
    click Tok "https://github.com/hai-on-op/core/tree/main/src/contracts/tokens"
    click PM "https://github.com/hai-on-op/core/tree/main/src/contracts/proxies"
    click PA "https://github.com/hai-on-op/core/tree/main/src/contracts/proxies/actions"
    click Sett "https://github.com/hai-on-op/core/tree/main/src/contracts/settlement"
    click Util "https://github.com/hai-on-op/core/tree/main/src/contracts/utils"
    click CF "https://github.com/hai-on-op/core/tree/main/src/contracts/factories"
    click IF "https://github.com/hai-on-op/core/tree/main/src/interfaces/factories"
    click AU "https://github.com/hai-on-op/core/tree/main/docs/src/detailed/auctions"
    click SM "https://github.com/hai-on-op/core/tree/main/docs/src/detailed/modules"
    click PMd "https://github.com/hai-on-op/core/tree/main/docs/src/detailed/proxies"
    click EI "https://github.com/hai-on-op/core/tree/main/src/interfaces"
    click TS "https://github.com/hai-on-op/core/tree/main/test"
    click DC "https://github.com/hai-on-op/core/tree/main/.github/workflows"
    click FC "https://github.com/hai-on-op/core/blob/main/foundry.toml"
    click Doc "https://github.com/hai-on-op/core/tree/main/docs"

    %% Styles
    classDef coreGovernance fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef coreToken fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef coreProxy fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef coreSettlement fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef coreUtils fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef factory fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef interface fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef module fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef infra fill:#E0FFFF,stroke:#000,stroke-width:2px;
```
