# vintagewander/ethers-lottery architecture

> Architecture diagram of the GitHub repository vintagewander/ethers-lottery, 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/vintagewander/ethers-lottery
- Repository: https://github.com/vintagewander/ethers-lottery

## Overview

##### Project Type and Purpose
- This is a blockchain development project—a Hardhat-based Ethereum smart-contract system that implements a verifiably random, autonomous lottery using Chainlink VRF and Chainlink Keepers.
- It provides deployment scripts, automated tests (unit and staging), and utility scripts for verification and interaction.

##### File Structure Analysis
- Top level:
- hardhat.config.ts – Hardhat configuration (networks, plugins, API keys)
- scripts/ – Ad hoc interaction scripts (e.g., enterLottery.ts)
- deploy/ – Hardhat-deploy scripts (00-deploy-mocks, 01-deploy-raffle)
- contracts/ – Solidity lottery contract(s)
- test/unit & test/staging – Unit and testnet integration tests
- utils/verify.ts – Etherscan contract verification logic
- .env.example, tsconfig.json, package.json – config, dependencies, and environment variable template
- The structure is modular: contracts (business logic), deploy (deployment pipeline), scripts (runtime interactions), tests (quality assurance), utils (common helpers).

##### README Insights
- Describes required environment variables (RPC URL, private key, Chainlink subscription ID, API keys).
- Shows workflow: compile → deploy to Sepolia → fund Chainlink subscription → register keepers → interact with contract
- External services: Alchemy (RPC), Chainlink VRF & Keepers, Etherscan (verification), CoinMarketCap (gas pricing).

a. Main Components
- Developer Workstation (Hardhat CLI & scripts)
- Ethereum Network (Sepolia testnet or mainnet)
- Smart Contract (Lottery.sol)
- Chainlink VRF Oracle Network
- Chainlink Keepers Network
- RPC Provider (Alchemy or Infura)
- Etherscan API (contract verification)
- External Data Source (CoinMarketCap API, optional)
- Local / CI Test Network (Hardhat local node)
b. Relationships and Data Flows
- Developer invokes compile/deploy scripts → Hardhat connects via RPC Provider → deploys contract to Ethereum network
- Deployed contract registers with Chainlink VRF → requests randomness → VRF responds on-chain
- Chainlink Keepers invoke on-chain upkeep (pick winner) on schedule
- Developer or CI runs unit/staging tests against either Hardhat local node or Sepolia
- After deployment, verify source code via Etherscan API
- Optional: tests or gas-estimate scripts fetch USD gas price from CoinMarketCap
c. Architectural Patterns & Principles
- Modular deployment pipeline (Hardhat-deploy)
- Separation of concerns: contracts vs. scripts vs. tests vs. utilities
- Config-driven environments (hardhat.config.ts + .env)
- On-chain event-driven design (VRF callbacks, Keepers upkeeps)
d. Key Technologies & Frameworks
- Hardhat (development environment, local node, tasks)
- TypeScript & Ethers.js (scripts and tests)
- Solidity (smart contracts)
- Chainlink VRF & Keepers (randomness & automation oracles)
- Alchemy or Infura (RPC)
- Etherscan API (verification)
- CoinMarketCap API (optional gas pricing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development Layer
    subgraph "Development Layer"
        direction TB
        HC["Hardhat CLI"]:::dev
        HCFG["hardhat.config.ts"]:::dev
        ENV[".env.example"]:::dev
        TSCFG["tsconfig.json"]:::dev
        PKG["package.json"]:::dev
        README["README.md"]:::dev
        Scripts["enterLottery.ts"]:::dev
        UnitTest["Lottery.unit test"]:::dev
        StagingTest["Lottery.staging test"]:::dev
        HC --> HCFG
        HC --> ENV
        HC --> TSCFG
        HC --> PKG
        HC --> README
        HC --> Scripts
        HC --> UnitTest
        HC --> StagingTest
    end

    %% Deployment & Verification Layer
    subgraph "Deployment & Verification Layer"
        direction TB
        HDP["Hardhat-deploy Pipeline"]:::deployment
        Mocks["00-deploy-mocks.ts"]:::deployment
        RaffleDEP["01-deploy-raffle.ts"]:::deployment
        RPC["RPC Provider\n(Alchemy/Infura)"]:::deployment
        VerifyUtil["verify.ts"]:::deployment
        EtherscanAPI["Etherscan API"]:::deployment
        HDP --> Mocks
        HDP --> RaffleDEP
        HDP --> RPC
        RPC -->|"deployment RPC calls"| Ethereum
        RaffleDEP --> RPC
        Mocks --> RPC
        VerifyUtil --> EtherscanAPI
        RPC --> VerifyUtil
    end

    %% On-Chain Layer
    subgraph "On-Chain Layer"
        direction TB
        LocalNode["Hardhat Local Node"]:::onchain
        Ethereum["Ethereum Network\n(Sepolia/Mainnet)"]:::onchain
        Lottery["Lottery Contract"]:::onchain
        VRF["Chainlink VRF Oracle"]:::onchain
        Keepers["Chainlink Keepers"]:::onchain
        HC --> LocalNode
        LocalNode --> Lottery
        Lottery -->|"register VRF"| VRF
        VRF -->|"callback randomness"| Lottery
        Lottery -->|"upkeep calls"| Keepers
        Keepers -->|"performUpkeep"| Lottery
        RPC --> Ethereum
        Ethereum --> Lottery
        VRF --> Ethereum
        Keepers --> Ethereum
    end

    %% External Services Layer
    subgraph "External Services Layer"
        direction TB
        CMC["CoinMarketCap API"]:::external
        Scripts --> CMC
        Scripts --> RPC
    end

    %% Click Events
    click HCFG "https://github.com/vintagewander/ethers-lottery/blob/main/hardhat.config.ts"
    click ENV "https://github.com/vintagewander/ethers-lottery/blob/main/.env.example"
    click TSCFG "https://github.com/vintagewander/ethers-lottery/blob/main/tsconfig.json"
    click PKG "https://github.com/vintagewander/ethers-lottery/blob/main/package.json"
    click README "https://github.com/vintagewander/ethers-lottery/blob/main/README.md"
    click Scripts "https://github.com/vintagewander/ethers-lottery/blob/main/scripts/enterLottery.ts"
    click Mocks "https://github.com/vintagewander/ethers-lottery/blob/main/deploy/00-deploy-mocks.ts"
    click RaffleDEP "https://github.com/vintagewander/ethers-lottery/blob/main/deploy/01-deploy-raffle.ts"
    click UnitTest "https://github.com/vintagewander/ethers-lottery/blob/main/test/unit/Lottery.test.ts"
    click StagingTest "https://github.com/vintagewander/ethers-lottery/blob/main/test/staging/Lottery.test.ts"
    click VerifyUtil "https://github.com/vintagewander/ethers-lottery/blob/main/utils/verify.ts"
    click HC "https://github.com/vintagewander/ethers-lottery/blob/main/./hardhat.config.ts"

    %% Styles
    classDef dev fill:#e0f7e9,stroke:#333,stroke-width:1px
    classDef deployment fill:#e1efff,stroke:#333,stroke-width:1px
    classDef onchain fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef external fill:#f3e5f5,stroke:#333,stroke-width:1px
```
