# cyfrin/foundry-smart-contract-lottery-cu architecture

> Architecture diagram of the GitHub repository cyfrin/foundry-smart-contract-lottery-cu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cyfrin/foundry-smart-contract-lottery-cu
- Repository: https://github.com/cyfrin/foundry-smart-contract-lottery-cu

## Overview

##### Project type and purpose
- This is a Solidity-based “Smart Contract Lottery” project built with Foundry.
- Purpose: demonstrate how to write, test (unit + forked), deploy, and interact with a raffle/lottery contract that uses Chainlink VRF for randomness and Chainlink Automation for upkeep.

##### File structure
- Top-level config & infra
- .env.example, foundry.toml, Makefile, GitHub Actions workflow
- .gitmodules → on-chain dependencies vendored under lib/
- img/ → screenshots for documentation
- Libraries (lib/)
- chainlink-brownie-contracts, forge-std, foundry-devops, solmate
- Source (src/)
- src/sublesson/ → your raffle contract(s) & helper config scripts
- Scripts (script/)
- Deployment & helper scripts written in Solidity (via foundry-devops)
- Tests (test/)
- unit/ → pure local tests
- staging/ → forked tests against Sepolia RPC URL
- mocks/ → Chainlink VRF mocks

##### Extract architecture insights from the README
- Developer workflow:
- forge build / forge test / forge coverage
- make anvil → boots a local Anvil node
- make deploy → runs deployment scripts against local or remote network
- External dependencies & services:
- Chainlink VRF (randomness)
- Chainlink Automation (upkeep)
- Sepolia node (via Alchemy RPC)
- Etherscan API (contract verification)

##### Main components & their interactions
a. Developer CLI / CI
- forge & cast (Foundry toolchain)
- Makefile shortcuts
- GitHub Actions CI pipeline
b. Local On-Chain Environment
- Anvil (local Ethereum node)
- Deployed Raffle contract
- VRFCoordinatorMock contract
c. Remote Network
- Sepolia RPC node (Alchemy)
- Deployed Raffle contract
d. Off-Chain Scripts
- Deployment scripts (script/HelperConfig.s.sol, script/Deploy.s.sol)
- Interaction scripts using cast
e. External Oracles/Services
- Chainlink VRF Coordinator (randomness provider)
- Chainlink Automation (upkeep registry)
- Etherscan (verification)

##### Architectural patterns & design principles
- Modular contract design: Raffle contract separated from subscription/config logic in HelperConfig
- Dependency vendoring: all required solidity libraries in lib/
- Multi-tier testing: pure unit, forked staging tests
- Infrastructure-as-Code: deployment orchestrated via scripts in Solidity (foundry-devops)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Tools
    subgraph "Developer Tools"
        ForgeCast(["Forge & Cast"]):::devTools
        Makefile(["Makefile Shortcuts"]):::devTools
        GitHubCI(["GitHub Actions CI"]):::devTools
    end

    %% Configuration & Documentation
    subgraph "Config & Docs"
        EnvExample([".env.example"]):::devTools
        FoundryConfig(["foundry.toml"]):::devTools
        Readme(["README.md"]):::devTools
        Images(["img/ (screenshots)"]):::devTools
    end

    %% Vendored Libraries
    libVend(["lib/ (vendored Solidity libraries)"]):::devTools

    %% Local Development Environment
    subgraph "Local Development"
        AnvilNode[["Anvil Node"]]:::onchain
        subgraph "Contracts & Tests"
            RaffleLocal(["Raffle.sol"]):::contract
            VRFMock(["VRFCoordinatorMock.sol"]):::contract
            UnitTests(["test/unit/"]):::devTools
            MocksLocal(["test/mocks/"]):::devTools
        end
    end

    %% Remote/Testnet Environment
    subgraph "Remote/Testnet (Sepolia)"
        SepoliaNode[["Sepolia RPC Node"]]:::onchain
        StagingTests(["test/staging/"]):::devTools
    end

    %% Off-Chain Scripts
    subgraph "Off-Chain Scripts"
        HelperConfig(["HelperConfig.s.sol"]):::script
        DeployScript(["Deploy.s.sol"]):::script
    end

    %% External Services
    subgraph "External Services"
        ChainlinkVRF(["Chainlink VRF Coordinator"]):::external
        ChainlinkAuto(["Chainlink Automation"]):::external
        Etherscan(["Etherscan API"]):::external
    end

    %% Flows
    ForgeCast -->|"build/test"| UnitTests
    ForgeCast -->|"run staging tests"| StagingTests
    GitHubCI -->|"CI pipeline"| ForgeCast
    GitHubCI -->|runs| UnitTests
    Makefile -->|"make anvil"| AnvilNode
    Makefile -->|"make deploy"| DeployScript
    DeployScript -->|deploy to local| AnvilNode
    DeployScript -->|deploy to Sepolia| SepoliaNode
    HelperConfig -->|config setup| RaffleLocal
    DeployScript -->|use config| HelperConfig
    AnvilNode -->|deploy| RaffleLocal
    AnvilNode -->|deploy| VRFMock
    RaffleLocal -->|requestRandomness| VRFMock
    VRFMock -->|fulfillRandomness| RaffleLocal
    SepoliaNode -->|deploy| RaffleLocal
    RaffleLocal -->|"requestRandomness"| ChainlinkVRF
    ChainlinkVRF -->|"fulfillRandomness"| RaffleLocal
    ChainlinkAuto -->|"upkeep call"| RaffleLocal
    DeployScript -->|"verify"| Etherscan
    HelperConfig -->|"uses .env, foundry.toml"| EnvExample
    libVend -->|vendored dependencies| RaffleLocal
    libVend -->|vendored dependencies| VRFMock

    %% Click Events
    click RaffleLocal "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/blob/main/src/sublesson/Raffle.sol"
    click HelperConfig "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/blob/main/script/HelperConfig.s.sol"
    click DeployScript "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/blob/main/script/Deploy.s.sol"
    click VRFMock "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/blob/main/test/mocks/VRFCoordinatorMock.sol"
    click UnitTests "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/tree/main/test/unit/"
    click StagingTests "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/tree/main/test/staging/"
    click MocksLocal "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/tree/main/test/mocks/"
    click FoundryConfig "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/blob/main/foundry.toml"
    click EnvExample "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/blob/main/.env.example"
    click Makefile "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/tree/main/Makefile"
    click GitHubCI "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/blob/main/.github/workflows/test.yml"
    click libVend "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/tree/main/lib/"
    click Readme "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/blob/main/README.md"
    click Images "https://github.com/cyfrin/foundry-smart-contract-lottery-cu/tree/main/img/"

    %% Styles
    classDef devTools fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef onchain fill:#98FB98,stroke:#333,stroke-width:1px
    classDef contract fill:#FFA500,stroke:#333,stroke-width:1px
    classDef script fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
