# percobain/pkmb architecture

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

- Interactive diagram: https://gitdiagram.com/percobain/pkmb
- Repository: https://github.com/percobain/pkmb

## Overview

##### Project type and purpose
- This is a full-stack Web3 dApp consisting of:
- A Solidity/Hardhat “contracts” backend for on-chain logic (ERC-20 token, ERC-721 NFT, and faucet contracts)
- A React/TypeScript “frontend” SPA served via Vite, integrating with MetaMask and IPFS
- Purpose: Let users claim PKMB tokens, mint NFTs with those tokens, and share NFTs on social media.

##### File structure
- Top-level:
- README.md, demo video
- contracts/ – Hardhat project (contracts/, scripts/, tests/, ignition/)
- frontend/ – React app (public assets, src folder with ABIs, UI components, pages, hooks, utilities, router)
- Patterns & config:
- SPA with client-side routing (frontend/src/router/routes.tsx)
- Standard React component hierarchy under src/components and src/pages
- Hardhat config for compiling, testing, and deploying contracts (hardhat.config.js)
- Deployment script (contracts/scripts/deploy.js)
- IPFS upload utilities for NFT metadata (frontend/src/utils/uploadToIpfs.ts)
- Environment config files (.env.development, .env.production)

##### Extract insights from the README
- Architecture described as two modules: Smart Contracts and Frontend
- Tech stack: React, TypeScript, Vite, TailwindCSS, ShadCn UI, Ethers.js, MetaMask, Solidity, Hardhat, IPFS
- Supported features: token faucet, NFT minting, social sharing integrations

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% UI Layer
  subgraph "UI Layer"
    User["End User"]:::external
    Main["React SPA"]:::ui
    App["Root App Component"]:::ui
    Routes["Client-Side Routing"]:::ui
    Landing["Landing Page"]:::ui
    FaucetPage["Faucet Page"]:::ui
    MyNFTsPage["My NFTs Page"]:::ui
    NftPage["NFT Detail Page"]:::ui
    ViewNftPage["View NFT Page"]:::ui
    UIlib["UI Component Library"]:::ui
    SharedUI["Shared UI Components"]:::ui
    Styles["Styling & Configuration"]:::ui
  end

  %% Web3 Integration
  subgraph "Web3 Integration"
    Ethers["Ethers.js"]:::web3
    MetaMask["MetaMask Provider"]:::web3
    AbisErc20["ERC-20 ABI"]:::web3
    AbisErc721["ERC-721 ABI"]:::web3
    AbisPkmb["PKMB721 ABI"]:::web3
    AbisFaucet["Faucet ABI"]:::web3
    UseMeta["useMetamask Hook"]:::web3
  end

  %% On-Chain Contracts
  subgraph "On-Chain Contracts"
    PKMBToken["PKMBToken Contract"]:::contracts
    PKMB721["PKMB721 NFT Contract"]:::contracts
    FaucetContract["Faucet Contract"]:::contracts
    EthereumNet["Ethereum Network"]:::external
  end

  %% Off-Chain Services
  subgraph "Off-Chain Services"
    IPFS["IPFS Network"]:::offchain
    Twitter["Twitter Share API"]:::offchain
    Upload["IPFS Upload Utility"]:::offchain
  end

  %% Deployment & Dev Workflow
  subgraph "Deployment & Dev Workflow"
    Vercel["Frontend Deployment (Vercel)"]:::dev
    HardhatCfg["Hardhat Configuration"]:::dev
    DeployScript["Contract Deployment Script"]:::dev
    Lock["Ignition Module: Lock"]:::dev
    TestFaucet["Faucet Tests"]:::dev
    TestPKMB721["PKMB721 Tests"]:::dev
    TestPKMBToken["PKMBToken Tests"]:::dev
  end

  %% Connections
  User --> Main
  Main --> App
  App --> Routes
  Routes --> Landing
  Routes --> FaucetPage
  Routes --> MyNFTsPage
  Routes --> NftPage
  Routes --> ViewNftPage
  App --> UIlib
  App --> SharedUI
  App --> Styles
  App --> Ethers
  Ethers --> MetaMask
  MetaMask --> UseMeta
  Ethers --> AbisErc20
  Ethers --> AbisErc721
  Ethers --> AbisPkmb
  Ethers --> AbisFaucet
  FaucetPage --> Upload
  NftPage --> Upload
  ViewNftPage --> Upload
  Upload --> IPFS
  App --> Twitter
  App --> Ethers
  Ethers --> PKMBToken
  Ethers --> PKMB721
  Ethers --> FaucetContract
  PKMBToken --> EthereumNet
  PKMB721 --> EthereumNet
  FaucetContract --> EthereumNet
  Main --> Vercel
  HardhatCfg --> DeployScript
  DeployScript --> PKMBToken
  DeployScript --> PKMB721
  DeployScript --> FaucetContract
  Lock --> DeployScript
  TestFaucet --> FaucetContract
  TestPKMB721 --> PKMB721
  TestPKMBToken --> PKMBToken

  %% Click Events
  click Main "https://github.com/percobain/pkmb/blob/main/frontend/src/main.tsx"
  click App "https://github.com/percobain/pkmb/blob/main/frontend/src/App.tsx"
  click Routes "https://github.com/percobain/pkmb/blob/main/frontend/src/router/routes.tsx"
  click Landing "https://github.com/percobain/pkmb/blob/main/frontend/src/pages/Landing.tsx"
  click FaucetPage "https://github.com/percobain/pkmb/blob/main/frontend/src/pages/Faucet.tsx"
  click MyNFTsPage "https://github.com/percobain/pkmb/blob/main/frontend/src/pages/MyNFTs.tsx"
  click NftPage "https://github.com/percobain/pkmb/blob/main/frontend/src/pages/Nft.tsx"
  click ViewNftPage "https://github.com/percobain/pkmb/blob/main/frontend/src/pages/ViewNftPage.tsx"
  click UIlib "https://github.com/percobain/pkmb/tree/main/frontend/src/components/ui/"
  click SharedUI "https://github.com/percobain/pkmb/tree/main/frontend/src/components/"
  click Styles "https://github.com/percobain/pkmb/blob/main/frontend/tailwind.config.js"
  click Styles "https://github.com/percobain/pkmb/blob/main/frontend/vite.config.ts"
  click Styles "https://github.com/percobain/pkmb/blob/main/frontend/src/styles/index.css"
  click UseMeta "https://github.com/percobain/pkmb/blob/main/frontend/src/hooks/useMetamask.tsx"
  click AbisErc20 "https://github.com/percobain/pkmb/blob/main/frontend/src/abis/erc20Abi.ts"
  click AbisErc721 "https://github.com/percobain/pkmb/blob/main/frontend/src/abis/erc721Abi.ts"
  click AbisPkmb "https://github.com/percobain/pkmb/blob/main/frontend/src/abis/pkmb721Abi.ts"
  click AbisFaucet "https://github.com/percobain/pkmb/blob/main/frontend/src/abis/faucetAbi.ts"
  click Upload "https://github.com/percobain/pkmb/blob/main/frontend/src/utils/uploadToIpfs.ts"
  click PKMBToken "https://github.com/percobain/pkmb/blob/main/contracts/contracts/PKMBToken.sol"
  click PKMB721 "https://github.com/percobain/pkmb/blob/main/contracts/contracts/PKMB721.sol"
  click FaucetContract "https://github.com/percobain/pkmb/blob/main/contracts/contracts/Faucet.sol"
  click HardhatCfg "https://github.com/percobain/pkmb/blob/main/contracts/hardhat.config.js"
  click DeployScript "https://github.com/percobain/pkmb/blob/main/contracts/scripts/deploy.js"
  click TestFaucet "https://github.com/percobain/pkmb/blob/main/contracts/test/Faucet.test.js"
  click TestPKMB721 "https://github.com/percobain/pkmb/blob/main/contracts/test/PKMB721.test.js"
  click TestPKMBToken "https://github.com/percobain/pkmb/blob/main/contracts/test/PKMBToken.test.js"
  click Lock "https://github.com/percobain/pkmb/blob/main/contracts/ignition/modules/Lock.js"

  %% Styles
  classDef ui fill:#cfe2ff,stroke:#0366d6,color:#000
  classDef web3 fill:#d1e7dd,stroke:#198754,color:#000
  classDef contracts fill:#ffe5b4,stroke:#fd7e14,color:#000
  classDef offchain fill:#e2d2f5,stroke:#6610f2,color:#000
  classDef dev fill:#f0f0f0,stroke:#6c757d,color:#000
  classDef external fill:#f8f9fa,stroke:#adb5bd,color:#000
```
