# mudgen/diamond-3-hardhat architecture

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

- Interactive diagram: https://gitdiagram.com/mudgen/diamond-3-hardhat
- Repository: https://github.com/mudgen/diamond-3-hardhat

## Overview

##### Project type and purpose
- This is an Ethereum smart-contract project using Hardhat, implementing the EIP-2535 Diamond Standard (a modular, upgradeable proxy pattern).
- Its goal is to deploy a single “diamond” proxy contract on‐chain, and then add, replace, or remove logic modules (“facets”) at runtime via the `diamondCut` function.

##### File structure
- Top‐level
– hardhat.config.js, package.json: Hardhat configuration and NPM scripts
– scripts/deploy.js: deployment and upgrade orchestration
– test/*.js: unit tests for diamondCut and loupe functions
- contracts/
– Diamond.sol: the proxy entry point
– facets/
- DiamondCutFacet.sol – implements the `diamondCut` upgrade interface
- DiamondLoupeFacet.sol – implements standard loupe (introspection) functions
- other facet .sol files (user–customizable logic)
– interfaces/: EIP-defined ABI interfaces
– libraries/LibDiamond.sol: shared storage layout and internal `diamondCut` logic
– upgradeInitializers/: initialization contracts for state setup on first upgrade

##### Insights from the README
- The README explains the deploy sequence:
1) Deploy DiamondCutFacet
2) Deploy Diamond proxy, passing owner & cut facet address
3) Deploy DiamondInit and call its `init` via delegatecall
4) Deploy other facets and call `diamondCut` to wire them into the proxy
- Tests cover both upgrade logic and loupe functions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Off-Chain Components
    subgraph "Off-Chain (Blue)" 
        direction TB
        HHconfig["hardhat.config.js"]:::offchain
        Package["package.json"]:::offchain
        DeployScript["scripts/deploy.js"]:::offchain
        ScriptLib["scripts/libraries/diamond.js"]:::offchain
        TestLoupe["test/diamondTest.js"]:::offchain
        TestCache["test/cacheBugTest.js"]:::offchain
        Readme["README.md"]:::offchain
    end

    %% On-Chain Components
    subgraph "On-Chain Contracts (Green/Orange)"
        direction TB
        DiamondProxy["contracts/Diamond.sol (Proxy)"]:::onchain
        LibDiamond["contracts/libraries/LibDiamond.sol"]:::library
        DiamondCut["contracts/facets/DiamondCutFacet.sol"]:::onchain
        DiamondLoupe["contracts/facets/DiamondLoupeFacet.sol"]:::onchain
        AddFacets["contracts/facets/*.sol (Additional Logic)"]:::onchain
        DiamondInit["contracts/upgradeInitializers/DiamondInit.sol"]:::onchain
    end

    %% Ethereum Network
    Ethereum["Ethereum Network"]:::network

    %% Client
    Client["Client (Ethers.js/Web3)"]:::client

    %% Deployment Flow
    DeployScript -->|uses Hardhat/Ethers.js| Ethereum
    DeployScript -->|deploys| DiamondCut
    DeployScript -->|deploys| DiamondProxy
    DeployScript -->|delegatecalls init| DiamondInit
    DeployScript -->|deploys & wires| AddFacets
    DiamondProxy -->|delegatecall| DiamondCut
    DiamondProxy -->|delegatecall| DiamondLoupe
    DiamondProxy -->|delegatecall| AddFacets
    DiamondProxy -->|uses storage| LibDiamond
    Client -->|calls via ABI| DiamondProxy

    %% Tests Interaction
    TestLoupe -->|calls loupe functions| DiamondProxy
    TestCache -->|reproduces cache bug| DiamondProxy

    %% Click Events
    click HHconfig "https://github.com/mudgen/diamond-3-hardhat/blob/main/hardhat.config.js"
    click Package "https://github.com/mudgen/diamond-3-hardhat/blob/main/package.json"
    click DeployScript "https://github.com/mudgen/diamond-3-hardhat/blob/main/scripts/deploy.js"
    click ScriptLib "https://github.com/mudgen/diamond-3-hardhat/blob/main/scripts/libraries/diamond.js"
    click TestLoupe "https://github.com/mudgen/diamond-3-hardhat/blob/main/test/diamondTest.js"
    click TestCache "https://github.com/mudgen/diamond-3-hardhat/blob/main/test/cacheBugTest.js"
    click Readme "https://github.com/mudgen/diamond-3-hardhat/blob/main/README.md"
    click DiamondProxy "https://github.com/mudgen/diamond-3-hardhat/blob/main/contracts/Diamond.sol"
    click DiamondCut "https://github.com/mudgen/diamond-3-hardhat/blob/main/contracts/facets/DiamondCutFacet.sol"
    click DiamondLoupe "https://github.com/mudgen/diamond-3-hardhat/blob/main/contracts/facets/DiamondLoupeFacet.sol"
    click AddFacets "https://github.com/mudgen/diamond-3-hardhat/tree/main/contracts/facets"
    click LibDiamond "https://github.com/mudgen/diamond-3-hardhat/blob/main/contracts/libraries/LibDiamond.sol"
    click DiamondInit "https://github.com/mudgen/diamond-3-hardhat/blob/main/contracts/upgradeInitializers/DiamondInit.sol"

    %% Styles
    classDef offchain fill:#D0E6FF,stroke:#034EA2,color:#034EA2;
    classDef onchain fill:#D0FFD6,stroke:#027A13,color:#027A13;
    classDef library fill:#FFE4B3,stroke:#CC8400,color:#CC8400;
    classDef network fill:#F0F0F0,stroke:#888888,color:#555555,stroke-dasharray: 5 5;
    classDef client fill:#E8D0FF,stroke:#5E00B1,color:#5E00B1;
```
