# flare-foundation/flare-hardhat-starter architecture

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

- Interactive diagram: https://gitdiagram.com/flare-foundation/flare-hardhat-starter
- Repository: https://github.com/flare-foundation/flare-hardhat-starter

## Overview

##### Project Type and Purpose
- This is a blockchain development starter kit built on Hardhat for the Flare Network.
- It provides a set of example Solidity contracts under `/contracts` and corresponding TypeScript scripts under `/scripts` to compile, deploy, and interact with those contracts.
- It is not a traditional full-stack web application; rather it’s a developer toolkit (an SDK/templates project) for writing, testing, and deploying smart contracts and oracle-based services on Flare.

##### File Structure Analysis
- Top-level files:
- `.env.example` / `.env` – environment for private keys and API keys
- `hardhat.config.ts` – Hardhat configuration listing Flare networks, compiler settings, plugins
- `package.json`, `tsconfig.json`, linter and prettier configs
- Directories:
- `contracts/` – Solidity smart contracts organized by feature: crossChainFdc, crossChainPayment, customFeeds, fassets, fdcExample, proofOfReserves, weatherInsurance
- `scripts/` – TypeScript scripts that compile/deploy/interact grouped the same way as contracts plus some utilities
- `utils/` – shared TypeScript helpers (e.g. network.ts)
- No web-UI frontend; interactions occur entirely through Hardhat scripts and plugins.

##### README Insights
- Emphasizes compilation (`npx hardhat compile`), testing, and deployment to Flare testnet/mainnet via Hardhat.
- Mentions use of Flare’s official periphery contracts package for mocking and integration.
- Encourages a clean starter approach: remove example contracts and scripts to start a new project.

##### Main Components
a. Smart Contract Layer
- Contracts in `/contracts/*` (e.g. FDC, payment, oracle feeds, insurance modules)
- Artifacts generated by Hardhat
b. Script/CLI Layer
- TypeScript scripts in `/scripts/*` using Hardhat Runtime Environment (HRE)
- Utility modules in `/scripts/utils` and `/utils`
c. Hardhat Engine
- `hardhat.config.ts` plugin system (Ethers.js, Waffle, Defender, etc.)
- Compilers and task runners
d. Network/External Services
- Flare blockchain nodes (Testnet/Mainnet RPC endpoints)
- Oracles or external data sources consumed by customFeeds and weatherInsurance
- Flare periphery contracts package (npm library)
e. Environment & Configuration
- `.env` for private keys, API keys
- Network parameters (URL, chain ID) in config files

##### Relationships and Data Flows
- Deployment flow: Script → HRE → compile → contract artifacts → RPC endpoint → deployed contract
- Interaction flow: Script imports deployed contract addresses → HRE → executes read/write calls → Flare node → blockchain state
- Oracle flow: Scripts fetch external data (e.g., metal prices, weather) → prepare and submit oracles requests → contracts process proofs/events
- Utilities: network.ts provides network selection and RPC configurations to all scripts.

##### Architectural Patterns & Principles
- Modular feature grouping (each `/contracts/X` with matching `/scripts/X`)
- Separation of concerns:
- Contracts only contain on‐chain logic
- Scripts handle deployment and orchestration off‐chain
- Utils abstract shared behavior (network config, common getters)
- Configuration-driven design: using environment variables and centralized config (`hardhat.config.ts`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Environment & Configuration"
        direction TB
        ENV_EX[".env.example"]:::config
        ENV[".env"]:::config
        HCONF["hardhat.config.ts"]:::config
    end

    %% Hardhat Engine
    subgraph "Hardhat Engine"
        direction TB
        HRE["Hardhat Runtime Environment"]:::config
    end

    %% Script/CLI Layer
    subgraph "Script/CLI Layer"
        direction TB
        SCF_SCRIPTS["scripts/crossChainFdc"]:::scripts
        SCP_SCRIPTS["scripts/crossChainPayment"]:::scripts
        CUSF_SCRIPTS["scripts/customFeeds"]:::scripts
        FAS_SCRIPTS["scripts/fassets"]:::scripts
        FDCEX_SCRIPTS["scripts/fdcExample"]:::scripts
        POR_SCRIPTS["scripts/proofOfReserves"]:::scripts
        WI_SCRIPTS["scripts/weatherInsurance"]:::scripts
        subgraph "Miscellaneous Scripts"
            direction TB
            GUESS["scripts/GuessingGame.ts"]:::scripts
            HW["scripts/HelloWorld.ts"]:::scripts
            FASTUP["scripts/fastUpdates.ts"]:::scripts
            ANCHOR["scripts/getAnchorPrices.ts"]:::scripts
            DEPLOY_CONS["scripts/deployFTSOConsumer.ts"]:::scripts
            TRYDEPLOY["scripts/tryDeployment.ts"]:::scripts
            WNAT["scripts/wnat"]:::scripts
            SUTIL_CORE["scripts/utils/core.ts"]:::scripts
            SUTIL_GET["scripts/utils/getters.ts"]:::scripts
            SUTIL_FA["scripts/utils/fassets.ts"]:::scripts
            SUTIL_FDC["scripts/utils/fdc.ts"]:::scripts
        end
        UTIL_NET["utils/network.ts"]:::scripts
    end

    %% Smart Contract Layer
    subgraph "Smart Contract Layer"
        direction TB
        SCF_CONTRACT["contracts/crossChainFdc"]:::smartContract
        SCP_CONTRACT["contracts/crossChainPayment"]:::smartContract
        CUSF_CONTRACT["contracts/customFeeds"]:::smartContract
        FAS_CONTRACT["contracts/fassets"]:::smartContract
        FDCEX_CONTRACT["contracts/fdcExample"]:::smartContract
        POR_CONTRACT["contracts/proofOfReserves"]:::smartContract
        WI_CONTRACT["contracts/weatherInsurance"]:::smartContract
    end

    %% External & Third-Party Services
    subgraph "External Services"
        direction TB
        FLARE_RPC["Flare RPC Nodes (Testnet/Mainnet)"]:::external
        ORACLES["External Data Sources / Oracles"]:::external
        PERIPH["Flare Periphery Contracts Package"]:::external
    end

    %% Flows
    ENV_EX -->|loads| HCONF
    ENV -->|loads| HCONF
    HCONF -->|configures| HRE

    SCF_SCRIPTS -->|invoke| HRE
    SCP_SCRIPTS -->|invoke| HRE
    CUSF_SCRIPTS -->|invoke| HRE
    FAS_SCRIPTS -->|invoke| HRE
    FDCEX_SCRIPTS -->|invoke| HRE
    POR_SCRIPTS -->|invoke| HRE
    WI_SCRIPTS -->|invoke| HRE
    GUESS -->|run| HRE
    HW -->|run| HRE
    FASTUP -->|run| HRE
    ANCHOR -->|run| HRE
    DEPLOY_CONS -->|run| HRE
    TRYDEPLOY -->|run| HRE
    WNAT -->|run| HRE
    SUTIL_CORE -->|import| SCF_SCRIPTS
    SUTIL_GET -->|import| SCF_SCRIPTS
    SUTIL_FA -->|import| FAS_SCRIPTS
    SUTIL_FDC -->|import| SCF_SCRIPTS
    UTIL_NET -->|import| SCF_SCRIPTS

    HRE -->|compile| SCF_CONTRACT
    HRE -->|compile| SCP_CONTRACT
    HRE -->|compile| CUSF_CONTRACT
    HRE -->|compile| FAS_CONTRACT
    HRE -->|compile| FDCEX_CONTRACT
    HRE -->|compile| POR_CONTRACT
    HRE -->|compile| WI_CONTRACT

    ORACLES -->|fetch data| CUSF_SCRIPTS
    ORACLES -->|fetch data| WI_SCRIPTS

    HRE -->|deploy| FLARE_RPC
    FLARE_RPC -->|deployed to| SCF_CONTRACT
    FLARE_RPC -->|deployed to| SCP_CONTRACT
    FLARE_RPC -->|deployed to| CUSF_CONTRACT
    FLARE_RPC -->|deployed to| FAS_CONTRACT
    FLARE_RPC -->|deployed to| FDCEX_CONTRACT
    FLARE_RPC -->|deployed to| POR_CONTRACT
    FLARE_RPC -->|deployed to| WI_CONTRACT

    SCF_SCRIPTS -->|invoke transaction| FLARE_RPC
    SCP_SCRIPTS -->|invoke transaction| FLARE_RPC
    CUSF_SCRIPTS -->|invoke transaction| FLARE_RPC
    FAS_SCRIPTS -->|invoke transaction| FLARE_RPC
    FDCEX_SCRIPTS -->|invoke transaction| FLARE_RPC
    POR_SCRIPTS -->|invoke transaction| FLARE_RPC
    WI_SCRIPTS -->|invoke transaction| FLARE_RPC

    PERIPH -->|linked by| SCF_CONTRACT
    PERIPH -->|linked by| SCP_CONTRACT
    PERIPH -->|linked by| CUSF_CONTRACT
    PERIPH -->|linked by| FAS_CONTRACT
    PERIPH -->|linked by| FDCEX_CONTRACT
    PERIPH -->|linked by| POR_CONTRACT
    PERIPH -->|linked by| WI_CONTRACT

    %% Click Events
    click SCF_CONTRACT "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/contracts/crossChainFdc"
    click SCP_CONTRACT "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/contracts/crossChainPayment"
    click CUSF_CONTRACT "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/contracts/customFeeds"
    click FAS_CONTRACT "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/contracts/fassets"
    click FDCEX_CONTRACT "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/contracts/fdcExample"
    click POR_CONTRACT "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/contracts/proofOfReserves"
    click WI_CONTRACT "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/contracts/weatherInsurance"

    click SCF_SCRIPTS "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/scripts/crossChainFdc"
    click SCP_SCRIPTS "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/scripts/crossChainPayment"
    click CUSF_SCRIPTS "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/scripts/customFeeds"
    click FAS_SCRIPTS "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/scripts/fassets"
    click FDCEX_SCRIPTS "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/scripts/fdcExample"
    click POR_SCRIPTS "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/scripts/proofOfReserves"
    click WI_SCRIPTS "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/scripts/weatherInsurance"

    click GUESS "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/GuessingGame.ts"
    click HW "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/HelloWorld.ts"
    click FASTUP "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/fastUpdates.ts"
    click ANCHOR "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/getAnchorPrices.ts"
    click DEPLOY_CONS "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/deployFTSOConsumer.ts"
    click TRYDEPLOY "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/tryDeployment.ts"
    click WNAT "https://github.com/flare-foundation/flare-hardhat-starter/tree/master/scripts/wnat"

    click UTIL_NET "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/utils/network.ts"
    click SUTIL_CORE "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/utils/core.ts"
    click SUTIL_GET "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/utils/getters.ts"
    click SUTIL_FA "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/utils/fassets.ts"
    click SUTIL_FDC "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/scripts/utils/fdc.ts"
    click ENV_EX "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/.env.example"
    click ENV "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/.env"
    click HCONF "https://github.com/flare-foundation/flare-hardhat-starter/blob/master/hardhat.config.ts"

    %% Styles
    classDef smartContract fill:#e2f7e1,stroke:#2d8a3d,stroke-width:1px;
    classDef scripts fill:#e1f0f7,stroke:#1f78b4,stroke-width:1px;
    classDef external fill:#fff3e0,stroke:#f57c00,stroke-width:1px;
    classDef config fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px;
```
