# codehawks-contests/2025-05-weather-witness architecture

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

- Interactive diagram: https://gitdiagram.com/codehawks-contests/2025-05-weather-witness
- Repository: https://github.com/codehawks-contests/2025-05-weather-witness

## Overview

##### Project type and purpose
- **Type:** Blockchain-based dynamic NFT dApp
- **Purpose:** Mint ERC721 tokens whose metadata (weather state) is fetched and updated automatically via Chainlink Functions (off-chain code) and Chainlink Automation (Keepers).

##### File structure
- **src/** (on-chain Solidity code)
- WeatherNft.sol (main contract)
- WeatherNftStore.sol (storage, events, data structures)
- **functionsSource/** (off-chain JavaScript code for Chainlink Functions)
- GetWeather.js – fetches and parses weather from OpenWeather API
- **deploy/**
- DeployWeatherNft.js – Hardhat script to deploy contracts & configure initial URIs
- **test/** and **utils/**
- forge tests, JS helpers for secret encryption and contract verification
- **config** files
- hardhat.config.js, foundry.toml, helper-hardhat-config.js
- **CI**
- .github/workflows/test.yml runs tests and lints

##### Extract architectural insights from the README
- Two core on-chain components: WeatherNft & WeatherNftStore
- Two off-chain Chainlink components:
- Functions node running GetWeather.js
- Automation (Keepers) checking heartbeat and triggering updates
- External API: OpenWeather for real-time data
- User roles: NFT Owner (wallet/UI) and Contract Owner (admin parameters)

a. **User Layer**
- Wallet or Web3 client (e.g., MetaMask, CLI)
- Interacts with smart contract via JSON-RPC
b. **Blockchain Layer**
- Avalanche Fu­ji (or any EVM) network node
- Smart contracts: WeatherNft.sol & WeatherNftStore.sol
- Chainlink Keeper Registry & Functions Router contracts
c. **Oracle Layer**
- Chainlink Functions Node
– Executes GetWeather.js
– Emits callback returning weather data to contract
- Chainlink Keepers Network
– Monitors heartbeats, calls checkUpkeep & performUpkeep
d. **External API**
- OpenWeather API (geocoding + current weather endpoints)
e. **Deployment & Tools**
- Hardhat & Foundry for compile, test, deploy
- Deployment script (DeployWeatherNft.js)
- Utility scripts for secret encryption & contract verification

##### Architectural patterns and design principles
- **Oracle Pattern:** on-chain contract delegates data fetching to off-chain Functions, uses callbacks
- **Event-Driven Automation:** Keepers watch for intervals (heartbeats) and trigger updates
- **Modular Separation:** on-chain (immutable contracts), off-chain (Functions), external services
- **Subscription Model:** each NFT optionally registers a Keeper subscription funded by a LINK deposit

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User Wallet / Web3 Client"]:::user
        User -->|"JSON-RPC Mint Request"| RPC["RPC Node (Avalanche Fuji)"]:::onchain
    end

    %% On-chain Layer
    subgraph "On-chain Layer"
        direction TB
        RPC -->|"invoke requestMintWeatherNFT()"| WeatherNft["WeatherNft (ERC721)"]:::onchain
        WeatherNftStore["WeatherNftStore (Storage & Events)"]:::onchain
        WeatherNft -->|"records data/events"| WeatherNftStore
        %% Chainlink Contracts
        KeeperRegistry["Chainlink Keeper Registry"]:::oracle
        FunctionsRouter["Chainlink Functions Router"]:::oracle
        WeatherNft -->|"subscribe for updates"| KeeperRegistry
        WeatherNft -->|"calls Functions Router"| FunctionsRouter
    end

    %% Oracle Layer
    subgraph "Oracle Layer"
        direction TB
        FunctionsRouter -->|"off-chain request"| FunctionsNode["Chainlink Functions Node"]:::offchain
        FunctionsNode -->|"executes GetWeather.js"| GetWeather["GetWeather.js"]:::offchain
        GetWeather -->|"fetch weather data"| OpenWeather
        GetWeather -->|"callback weather data"| FunctionsRouter
        KeeperNetwork["Chainlink Keepers Network"]:::oracle
        KeeperRegistry -->|"checkUpkeep/performUpkeep"| KeeperNetwork
        KeeperNetwork -->|"trigger new Functions call"| FunctionsRouter
    end

    %% External API Layer
    subgraph "External API"
        direction TB
        OpenWeather["OpenWeather API"]:::external
    end

    %% DevOps Layer
    subgraph "DevOps & CI"
        direction TB
        DeployScript["DeployWeatherNft.js"]:::devops
        HardhatConfig["hardhat.config.js"]:::devops
        FoundryConfig["foundry.toml"]:::devops
        HelperConfig["helper-hardhat-config.js"]:::devops
        Tests["test/ (Forge tests)"]:::devops
        SecretUtil["generateEncryptedSecret.js"]:::devops
        VerifyUtil["verifyContract.js"]:::devops
        CI[".github/workflows/test.yml"]:::devops
        Docs["README.md"]:::devops

        DeployScript -->|"deploy & init URIs"| WeatherNft
        Tests -->|"validate contracts"| WeatherNft
    end

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px
    classDef onchain fill:#bbdefb,stroke:#0d47a1,stroke-width:1px
    classDef oracle fill:#c8e6c9,stroke:#1b5e20,stroke-width:1px
    classDef offchain fill:#a5d6a7,stroke:#2e7d32,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#757575,stroke-width:1px
    classDef devops fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px

    %% Click Events
    click WeatherNft "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/src/WeatherNft.sol"
    click WeatherNftStore "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/src/WeatherNftStore.sol"
    click GetWeather "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/functionsSource/GetWeather.js"
    click DeployScript "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/deploy/DeployWeatherNft.js"
    click Tests "https://github.com/codehawks-contests/2025-05-weather-witness/tree/main/test/"
    click SecretUtil "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/utils/generateEncryptedSecret.js"
    click VerifyUtil "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/utils/verifyContract.js"
    click HardhatConfig "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/hardhat.config.js"
    click FoundryConfig "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/foundry.toml"
    click HelperConfig "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/helper-hardhat-config.js"
    click CI "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/.github/workflows/test.yml"
    click Docs "https://github.com/codehawks-contests/2025-05-weather-witness/blob/main/README.md"
```
