# damirs09/erc721a architecture

> Architecture diagram of the GitHub repository damirs09/erc721a, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/damirs09/erc721a
- Repository: https://github.com/damirs09/erc721a

## Overview

##### Project Type and Purpose
- This is an Ethereum smart‑contract project (NFT token) managed with Hardhat.
- Purpose: compile, test, and deploy an ERC‑721A‑based NFT contract that exposes tokenURI, contractURI, and royaltyInfo, with metadata hosted off‑chain (e.g., IPFS).

##### File Structure Analysis
- Top level:
- package.json / package-lock.json → npm dependencies (Hardhat, Ethers.js, Mocha, Chai, coverage).
- hardhat.config.js → network and plugin configuration.
- .env.Example → env vars (e.g., PRIVATE_KEY, RPC endpoints).
- contracts/ → Solidity sources (your NFT contract).
- scripts/deploy.js → deployment script using Hardhat Runtime Environment (HRE) & Ethers.js.
- test/ → Mocha/Chai tests leveraging Hardhat network and fixtures.

##### README Insights
- Describes key contract functions: tokenURI (per‑token metadata URI), contractURI (collection‑level metadata), royaltyInfo (EIP‑2981 royalties).
- Provides CLI commands:
- Testing: npx hardhat test
- Coverage: npx hardhat coverage
- Deployment: npx hardhat run --network testnet scripts/deploy.js

a. Main Components
1. Developer Workstation (IDE, npm CLI)
2. Hardhat Tooling
- Compiler & Artifacts
- Local Test Network (in‑memory Ethereum VM)
- Hardhat Runtime Environment (HRE)
3. Solidity Contracts (contracts/)
4. Test Suite (test/)
5. Deployment Script (scripts/deploy.js)
6. External Networks
- Ethereum Testnet (e.g., Goerli)
- IPFS (metadata storage)
7. Smart Contract on‑chain instance
b. Relationships & Interactions
- Developer invokes “npx hardhat compile” → Hardhat compiles contracts → artifacts generated.
- “npx hardhat test” → HRE spins up local node → tests execute methods on fresh deployments.
- “npx hardhat run --network testnet scripts/deploy.js” → HRE loads network config → Ethers.js deploys contract to testnet.
- On‑chain contract methods (tokenURI, contractURI) read URIs pointing to IPFS. royaltyInfo calculates royalty recipients.
c. Architectural Patterns & Principles
- Separation of Concerns: contracts vs. deploy scripts vs. tests.
- Plugin‑based extension: Hardhat plugins for Ethers, coverage.
- Off‑chain metadata storage: leveraging IPFS for scalability and immutability.
- Standard interfaces: ERC‑721A for gas‑efficient NFTs, EIP‑2981 for royalties.
d. Key Technologies & Frameworks
- Solidity (contracts/)
- Hardhat (build & test framework)
- Ethers.js (in deploy scripts & tests)
- Mocha/Chai (testing)
- IPFS (metadata hosting)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Workstation
    subgraph "Developer Workstation" 
        CLI["npm CLI & IDE"]:::offchain
    end

    %% Hardhat Tooling
    subgraph "Hardhat Tooling" 
        Compiler["Compiler & Artifacts"]:::offchain
        HRE["Hardhat Runtime Environment"]:::offchain
        LocalNode["Hardhat Local Node (in‑memory VM)"]:::offchain
    end

    %% Codebase
    subgraph "Project Codebase" 
        Contracts["Solidity Contracts"]:::code
        DeployScript["Deployment Script"]:::code
        Tests["Test Suite"]:::code
        Config["Hardhat Configuration"]:::code
        EnvExample["Environment Variables Example"]:::code
        PackageJSON["package.json"]:::code
        PackageLock["package-lock.json"]:::code
        Readme["README.md"]:::code
        Gitignore[".gitignore"]:::code
        Vscode[".vscode/"]:::code
    end

    %% External Services
    subgraph "External Services" 
        IPFS[(IPFS Storage)]:::external
    end

    %% Networks
    subgraph "Blockchain Networks"
        Testnet["Ethereum Testnet"]:::onchain
    end

    %% On-chain Contract Instance
    ContractInstance["Deployed NFT Contract"]:::onchain

    %% Workflows
    CLI -->|"compile"| Compiler
    Compiler -->|generates artifacts| HRE
    CLI -->|"test"| HRE
    HRE -->|"spins up"| LocalNode
    LocalNode -->|runs tests on| Contracts
    Tests -->|invoke methods| LocalNode

    CLI -->|"run deploy"| HRE
    HRE -->|uses Ethers.js| DeployScript
    DeployScript -->|"deploys to"| Testnet
    Testnet -->|hosts| ContractInstance

    ContractInstance -->|reads metadata URI| IPFS
    ContractInstance -->|royaltyInfo| IPFS

    %% Codebase links
    Contracts -->|imported by| Compiler
    Config -->|used by| HRE
    EnvExample -->|provides keys to| HRE
    PackageJSON -->|defines deps| CLI
    PackageLock -->|locks deps| CLI
    Readme -->|documents| CLI
    Gitignore -->|excludes| CLI
    Vscode -->|editor settings| CLI

    %% Click Events
    click Contracts "https://github.com/damirs09/erc721a/tree/main/contracts/"
    click DeployScript "https://github.com/damirs09/erc721a/blob/main/scripts/deploy.js"
    click Tests "https://github.com/damirs09/erc721a/blob/main/test/BubbleToken721A_TEST.js"
    click Config "https://github.com/damirs09/erc721a/blob/main/hardhat.config.js"
    click EnvExample "https://github.com/damirs09/erc721a/blob/main/.env.Example"
    click PackageJSON "https://github.com/damirs09/erc721a/blob/main/package.json"
    click PackageLock "https://github.com/damirs09/erc721a/blob/main/package-lock.json"
    click Readme "https://github.com/damirs09/erc721a/blob/main/README.md"
    click Gitignore "https://github.com/damirs09/erc721a/blob/main/.gitignore"
    click Vscode "https://github.com/damirs09/erc721a/tree/main/.vscode/"

    %% Styles
    classDef onchain fill:#D0E8FF,stroke:#0366D6;
    classDef offchain fill:#E8F5D1,stroke:#228B22;
    classDef external fill:#FFE8D1,stroke:#FF8C00;
    classDef code fill:#F0F0F0,stroke:#666;
    classDef default stroke:#333,stroke-width:1px;
```
