# valterlobo/phygital_assets architecture

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

- Interactive diagram: https://gitdiagram.com/valterlobo/phygital_assets
- Repository: https://github.com/valterlobo/phygital_assets

## Overview

##### Project Type and Purpose
- This is a blockchain smart‐contract project built with Foundry (“forge,” “anvil,” “cast”).
- Purpose: “Phygital Assets” platform to tokenize physical goods as ERC-721 NFTs, deployable to Ethereum (or test) networks.
- Key workflows: deploy contracts, mint NFTs via on‐chain scripts, run automated tests and gas snapshots.

##### File Structure Analysis
- Top‐level:
- lib/forge-std, lib/openzeppelin-contracts – external Solidity libraries for testing and ERC-721 implementation
- src/ – PhygitalAssets.sol and related contract code
- script/ – Solidity deployment & minting scripts (PhygitalAssetsDeploy.s.sol, PhygitalAssetsMint.s.sol)
- test/ – Foundry test suites
- .github/workflows/test.yml – CI configuration to run `forge test`
- .env.example – RPC URLs, private keys for off‐chain tooling
- Foundry handles build, test, format, snapshot and local chain (anvil).

##### README Insights
- Shows commands for build (`forge build`), test (`forge test`), deploy & mint scripts with `forge script … --rpc-url … --broadcast`
- Mentions provider services (Infura, Alchemy) configured via `.env`

##### Main Components
a. On-Chain Components
- PhygitalAssets Smart Contract (ERC-721)
- Underlying OpenZeppelin ERC-721 library
- Ethereum Network (Testnet or Mainnet)
b. Off-Chain Components
- Developer Machine / CI Agent
- Foundry Toolchain (forge, cast, anvil)
- Deployment & Mint Scripts
- .env Configuration (RPC URL, keys)
- External RPC Providers (Infura, Alchemy)
- Testing Framework (forge test)
- GitHub Actions (CI pipeline)

##### Relationships and Data Flow
- Developer invokes forge/anvil locally for unit tests → tests import src/ and lib/ → simulate chain
- Deploy Script reads .env → calls RPC provider → broadcasts contract bytecode to Ethereum
- Mint Script calls contract’s mint function → stores metadata & NFT on-chain
- CI pipeline runs `forge test` on push (via GitHub Actions)
- cast commands (optional) query or interact with deployed contract

##### Architectural Patterns & Principles
- Modular contracts using OpenZeppelin libraries for security and upgrades
- Separation of concerns:
- src/ contains production code
- lib/ holds external dependencies
- script/ isolates deployment logic
- test/ covers contract behavior
- Infrastructure as Code: scripts + environment files define deployments
- CI/CD integration via GitHub workflows

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Off-Chain Tools & Scripts
    subgraph "Off-Chain Tools & Scripts"
        DevMachine["Developer Machine / CI Agent"]:::tool
        Foundry["Foundry Toolchain\n(forge, cast, anvil)"]:::tool
        subgraph "Scripts"
            Deploy["PhygitalAssetsDeploy.s.sol"]:::tool
            Mint["PhygitalAssetsMint.s.sol"]:::tool
        end
        Config[".env Configuration"]:::config
        README["README.md"]:::config
    end

    %% On-Chain Components
    subgraph "On-Chain Components"
        src["src/PhygitalAssets.sol\n(ERC-721)"]:::onchain
        OZ["Underlying OpenZeppelin ERC-721 Library\n(lib/openzeppelin-contracts/)"]:::onchain
        FS["Foundry Standard Library\n(lib/forge-std/)"]:::onchain
    end

    %% Local and Remote Chains
    subgraph "Chains"
        Anvil["Local Anvil Chain"]:::chain
        Ethereum["Ethereum Network\n(Mainnet/Testnet)"]:::chain
    end

    %% Testing Framework
    subgraph "Testing"
        Tests["test/"]:::tool
    end

    %% External Services
    subgraph "External Services"
        RPC["Infura / Alchemy\n(RPC Provider)"]:::external
        GitHub["GitHub Actions\n(.github/workflows/test.yml)"]:::external
    end

    %% Relationships
    DevMachine --> Foundry
    DevMachine --> README
    Foundry --> Tests
    Tests --> Anvil
    Anvil --> src
    Foundry --> Deploy
    Foundry --> Mint
    Deploy --> Config
    Mint --> Config
    Deploy --> RPC
    Mint --> RPC
    RPC --> Ethereum
    GitHub --> Foundry
    GitHub --> Tests

    %% Click Events
    click src "https://github.com/valterlobo/phygital_assets/blob/main/src/PhygitalAssets.sol"
    click OZ "https://github.com/valterlobo/phygital_assets/tree/main/lib/openzeppelin-contracts/"
    click FS "https://github.com/valterlobo/phygital_assets/tree/main/lib/forge-std/"
    click Deploy "https://github.com/valterlobo/phygital_assets/blob/main/script/PhygitalAssetsDeploy.s.sol"
    click Mint "https://github.com/valterlobo/phygital_assets/blob/main/script/PhygitalAssetsMint.s.sol"
    click Tests "https://github.com/valterlobo/phygital_assets/tree/main/test/"
    click Config "https://github.com/valterlobo/phygital_assets/blob/main/.env.example"
    click GitHub "https://github.com/valterlobo/phygital_assets/blob/main/.github/workflows/test.yml"
    click README "https://github.com/valterlobo/phygital_assets/blob/main/README.md"

    %% Styles
    classDef onchain fill:#e0ffe0,stroke:#00aa00;
    classDef tool fill:#e0f0ff,stroke:#0077cc;
    classDef external fill:#fff4e0,stroke:#ff8800;
    classDef config fill:#f0e0ff,stroke:#aa00aa;
    classDef chain fill:#e0ffe0,stroke:#00aa00;
```
