# hemanthghs/sui-nft-marketplace architecture

> Architecture diagram of the GitHub repository hemanthghs/sui-nft-marketplace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hemanthghs/sui-nft-marketplace
- Repository: https://github.com/hemanthghs/sui-nft-marketplace

## Overview

##### Project type and purpose
- This is a full-stack decentralized application (dApp) consisting of:
- A React-based frontend (under `frontend/`)
- On-chain Move smart contracts (under `sources/`) deployed to a Sui blockchain
- A local Sui testnet and client interactions (configured via CLI and JSON-RPC)
- Purpose: Build an NFT marketplace on Sui with minting, listing, buying, fees, stats.

##### File structure
- Top-level:
- `frontend/` — UI code (TSX, Vite, networkConfig, wallet integration)
- `sources/` — Move modules (`nft_marketplace.move`, `marketplace.move`)
- `tests/` — Move unit tests for marketplace logic
- Config: `Move.toml`, `Move.lock`, `.gitignore`, `README.md`
- Patterns:
- Frontend ↔ Sui JSON-RPC calls (no separate REST API)
- On-chain modules use shared object pattern for marketplace state
- Tests exercise Move modules directly

##### README
- Confirms architecture: React UI calls Sui CLI / JSON-RPC
- Describes modules for NFT creation (`nft_marketplace`) and trading (`marketplace`)
- Outlines Sui local testnet environment and step-by-step flows

##### Detail
- React component (App, CreateNFT, OwnedObjects, WalletStatus) as part of the frontend layer
- `networkConfig.ts` feeding RPC URLs into the UI
- Move build & publish process (Move.toml → compilation → deployed package ID)
- Fee flow: buyer payment → marketplace fee_balance → seller payout
- Errors and assertions as part of contract logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and components
    subgraph "User Interaction" 
        direction TB
        User["User"]:::external
    end

    subgraph "Frontend Layer" 
        direction TB
        FE_APP["React App (App.tsx)"]:::frontend
        FE_Create["CreateNFT Component"]:::frontend
        FE_Owned["OwnedObjects Component"]:::frontend
        FE_Wallet["WalletStatus Component"]:::frontend
        FE_NetConf["networkConfig.ts"]:::config
        FE_Vite["vite.config.mts"]:::config
        FE_Pkg["package.json"]:::config
        FE_Readme["frontend/README.md"]:::config
        FE_GitIgnore["frontend/.gitignore"]:::config
    end

    subgraph "Blockchain Node" 
        direction TB
        Node["Sui JSON-RPC Node"]:::blockchain
        CLI["Sui CLI Scripts"]:::config
    end

    subgraph "On-Chain Modules" 
        direction TB
        NFT_Mod["NFT Module"]:::contracts
        Mkt_Mod["Marketplace Module"]:::contracts
        Auction_Mod["Auction Module"]:::contracts
    end

    subgraph "On-Chain Storage" 
        direction TB
        Store["Object Store (Tables & Balances)"]:::storage
    end

    subgraph "Testing Harness" 
        direction TB
        Tests["Move Unit Tests"]:::tests
    end

    subgraph "Project Configuration" 
        direction TB
        MoveToml["Move.toml"]:::config
        MoveLock["Move.lock"]:::config
        RootReadme["README.md"]:::config
        GitIgnore[".gitignore"]:::config
    end

    %% Connections
    User -->|"interacts with"| FE_APP
    FE_APP -->|"renders"| FE_Create
    FE_APP -->|"renders"| FE_Owned
    FE_APP -->|"renders"| FE_Wallet
    FE_APP -->|"uses"| FE_NetConf
    FE_APP -->|"configured by"| FE_Vite
    FE_APP -->|"dependencies"| FE_Pkg

    FE_APP -->|"RPC calls"| Node
    FE_Wallet -->|"connects"| Node

    CLI -->|"executes entry functions"| Node
    Node -->|"executes"| NFT_Mod
    Node -->|"executes"| Mkt_Mod
    Node -->|"executes"| Auction_Mod

    NFT_Mod -->|"manages state in"| Store
    Mkt_Mod -->|"manages listings in"| Store
    Auction_Mod -->|"manages auctions in"| Store

    Tests -->|"invoke functions in"| NFT_Mod
    Tests -->|"invoke functions in"| Mkt_Mod

    MoveToml -->|"defines packages"| NFT_Mod
    MoveToml -->|"defines packages"| Mkt_Mod
    MoveToml -->|"defines packages"| Auction_Mod
    MoveLock -->|"locks dependencies"| MoveToml

    RootReadme -->|"documents architecture"| FE_APP
    RootReadme -->|"documents architecture"| Node
    FE_Readme -->|"documents setup"| FE_APP

    GitIgnore -->|"ignores files"| .
    FE_GitIgnore -->|"ignores files"| frontend

    %% Click Events
    click FE_APP "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/src/App.tsx"
    click FE_Create "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/src/CreateNFT.tsx"
    click FE_Owned "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/src/OwnedObjects.tsx"
    click FE_Wallet "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/src/WalletStatus.tsx"
    click FE_NetConf "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/src/networkConfig.ts"
    click FE_Vite "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/vite.config.mts"
    click FE_Pkg "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/package.json"
    click NFT_Mod "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/sources/nft_marketplace.move"
    click Mkt_Mod "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/sources/marketplace.move"
    click Auction_Mod "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/sources/auction.move"
    click MoveToml "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/Move.toml"
    click MoveLock "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/Move.lock"
    click Tests "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/tests/nft_marketplace_tests.move"
    click RootReadme "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/README.md"
    click FE_Readme "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/README.md"
    click GitIgnore "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/.gitignore"
    click FE_GitIgnore "https://github.com/hemanthghs/sui-nft-marketplace/blob/master/frontend/.gitignore"

    %% Styles
    classDef frontend fill:#CCE5FF,stroke:#3399FF,stroke-width:2px;
    classDef blockchain fill:#D1F2EB,stroke:#1ABC9C,stroke-width:2px;
    classDef contracts fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef storage fill:#E8F8F5,stroke:#2ECC71,stroke-width:2px,stroke-dasharray: 5 5;
    classDef tests fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef config fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef external fill:#FFFFFF,stroke:#7F8C8D,stroke-width:2px,stroke-dasharray: 2 2;
```
