# jsharles/qb3 architecture

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

- Interactive diagram: https://gitdiagram.com/jsharles/qb3
- Repository: https://github.com/jsharles/qb3

## Overview

##### Project type and purpose
- This is a full-stack “DePIN” logistics proof-of-concept dApp (“QB3”) using Ethereum smart contracts for last-mile delivery.
- The goal is to issue ERC-20 (QB3Token) and ERC-721 (SpaceRegistry) tokens, interact via a Next.js frontend, store off-chain data in Prisma, and deploy on Sepolia with CI/CD.

##### File structure
- Monorepo with two top-level folders:
– backend/ → Hardhat project (Solidity contracts, deployment scripts under ignition/, tests, config)
– frontend/ → Next.js 15 app (Tailwind CSS, Prisma schema & migrations, React components, Wagmi/Viem for Web3)
- CI: .github/workflows/test.yml
- VSCode config, linting, build scripts, type configurations

##### README for additional insights
- Smart contracts: QB3Token.sol and SpaceRegistry.sol
- Frontend: Next.js + Tailwind + RainbowKit + wagmi + viem
- CI: GitHub Actions, deployments: Vercel (frontend) and Sepolia (blockchain)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["User’s Browser"]:::frontend
        Nextjs["Next.js Server (SSR & API)"]:::frontend
        Web3["Web3 Client (wagmi + viem + RainbowKit)"]:::frontend
    end

    %% Off-chain Backend
    subgraph "Off-chain Backend"
        direction TB
        DB["Prisma DB"]:::db
    end

    %% On-chain Layer
    subgraph "On-chain Layer"
        direction TB
        SepoliaRPC["Sepolia Testnet RPC"]:::onchain
        QB3Token["QB3Token.sol"]:::contract
        SpaceRegistry["SpaceRegistry.sol"]:::contract
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CI["GitHub Actions"]:::cicd
        Vercel["Vercel Deploy (Frontend)"]:::cicd
        HardhatTests["Contract Tests & Hardhat Config"]:::cicd
    end

    %% Connections
    Browser -->|"SSR/CSR interactions"| Nextjs
    Browser -->|"Client-side hooks"| Web3
    Nextjs -->|"Reads/Writes"| DB
    Nextjs -->|"RPC provider"| SepoliaRPC
    Web3 -->|"Blockchain read/write"| SepoliaRPC

    SepoliaRPC -->|"Interacts on-chain"| QB3Token
    SepoliaRPC -->|"Interacts on-chain"| SpaceRegistry

    SepoliaRPC -->|"deploy via Hardhat"| DeployModule["Hardhat Deployment Module"]:::backenddev
    DeployModule -->|"artifacts"| DeployArtifacts["Deployments (chain-11155111)"]:::backenddev

    CI -->|"run tests & lint"| Nextjs
    CI -->|"run tests"| DeployModule
    CI -->|"deploy to Vercel"| Vercel

    CI -->|"run smart contract tests"| HardhatTests

    %% Click Events
    click Browser "https://github.com/jsharles/qb3/tree/main/frontend/src/app"
    click Nextjs "https://github.com/jsharles/qb3/blob/main/frontend/next.config.ts"
    click DB "https://github.com/jsharles/qb3/blob/main/frontend/prisma/schema.prisma"
    click Web3 "https://github.com/jsharles/qb3/blob/main/frontend/src/wagmi.ts"
    click SepoliaRPC "https://github.com/jsharles/qb3/blob/main/frontend/src/lib/constants/index.ts"
    click QB3Token "https://github.com/jsharles/qb3/blob/main/backend/contracts/QB3Token.sol"
    click SpaceRegistry "https://github.com/jsharles/qb3/blob/main/backend/contracts/SpaceRegistry.sol"
    click DeployModule "https://github.com/jsharles/qb3/blob/main/backend/ignition/modules/DeployQB3.ts"
    click DeployArtifacts "https://github.com/jsharles/qb3/tree/main/backend/ignition/deployments/chain-11155111"
    click CI "https://github.com/jsharles/qb3/blob/main/.github/workflows/test.yml"
    click HardhatTests "https://github.com/jsharles/qb3/blob/main/backend/test/SpaceRegistry.ts"
    click HardhatTests "https://github.com/jsharles/qb3/blob/main/backend/hardhat.config.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#3399FF,stroke-width:2px
    classDef db fill:#E6FFE6,stroke:#33CC33,stroke-width:2px
    classDef onchain fill:#FFF4E6,stroke:#FF9933,stroke-width:2px
    classDef contract fill:#FFEFE6,stroke:#FF6600,stroke-width:2px
    classDef backenddev fill:#F0F0F0,stroke:#999999,stroke-width:2px
    classDef cicd fill:#F4E6FF,stroke:#9933FF,stroke-width:2px
```
