# jainsamyak15/pepper architecture

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

- Interactive diagram: https://gitdiagram.com/jainsamyak15/pepper
- Repository: https://github.com/jainsamyak15/pepper

## Overview

##### Project type and purpose
- This is a full-stack decentralized application (dApp) built with Next.js (App Router) as the frontend, React components, Tailwind CSS, and a set of Solidity smart contracts under `contracts/`.
- Purpose: A peer-to-peer sports prediction market (“Pepper”) where official team managers create markets and fans place back/lay bets using team-specific Fan Tokens on the Chiliz blockchain.

##### File structure
- Top-level:
- `contracts/` – Solidity contracts defining market logic, roles, fees, matching engine.
- `scripts/deploy.js` – Deployment script for the smart contract.
- `src/app/` – Next.js pages (App Router) for public pages (`/markets`, `/teams`, `/create-market`, `/admin/dashboard`, etc.).
- `src/components/` – Reusable UI components (market cards, order book, forms, wallet connector).
- `src/hooks/` – Custom React hooks (`useWallet`, `useMarkets`, `useTeams`) for state and contract interactions.
- `src/utils/contract.ts` – Ethers/Web3 interface to the deployed contract.
- Config files: Next.js (`next.config.mjs`), Tailwind (`tailwind.config.ts`), ESLint/TypeScript settings.

##### Key insights from the README
- Roles: Admin, Team Manager, Users
- Core flows: wallet connection → browse/create markets → place/cancel orders → match engine → resolve markets → redeem winnings.
- On-chain order matching, fee collection, and role-based access control.

##### Main components
a. Frontend (Next.js + React)
- Pages (`src/app/*`)
- UI Components (`src/components/*`)
- Hooks (`src/hooks/*`)
b. Blockchain Layer
- Smart Contract (`contracts/Pepper.sol`) with modules: RBAC, market factory, order matching, resolution, fee logic.
- Deployment (scripts/deploy.js) to the Chiliz EVM.
c. Wallet Provider
- MetaMask or any Web3 wallet (interfaced via `useWallet`)
d. External Services (optional/future)
- Sports data API (for real-time feeds)
- Governance/voting contracts

##### Relationships and data flows
- Frontend → Web3 Provider (injected by MetaMask)
- Web3 Provider → Ethers.js → Smart Contract on Chiliz blockchain (JSON-RPC)
- Smart Contract → on-chain state (markets, orders, roles, token balances)
- Optional: off-chain APIs → Frontend (for sports data, analytics)

##### Architectural patterns & design principles
- File-based routing (Next.js App Router) – separate pages by directory.
- Component hierarchy – `<Header>`, `<Footer>`, `<MarketCard>`, `<OrderBook>`, `<PlaceOrderForm>`.
- Hook abstraction – encapsulate contract reads/writes in `useMarkets` and `useWallet`.
- Separation of concerns – UI vs. data layer (Ethers abstractions in `src/utils/contract.ts`).
- On-chain business logic – state machine for market lifecycle; no central server liability.

##### Technologies & frameworks
- Next.js (React, App Router, SSR/SSG)
- Tailwind CSS for styling
- Ethers.js for blockchain interactions
- Solidity for smart contracts
- Node.js scripts for contract deployment

##### Essential elements
- Component boundaries (Frontend vs. Blockchain)
- Deployment pipeline: `scripts/deploy.js` → Chiliz test/mainnet

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User’s Browser"]:::external

    %% Frontend Application Entry
    FrontendApp["Next.js Frontend"]:::frontend

    User -->|"HTTP/HTTPS"| FrontendApp

    %% Frontend Subgraphs
    subgraph "Frontend: Pages" 
        direction TB
        HomePage["Home Page"]:::frontend
        MarketsList["Markets List"]:::frontend
        CreateMarket["Create Market"]:::frontend
        Profile["Profile"]:::frontend
        TeamManagerDashboard["Team Manager Dashboard"]:::frontend
        AdminDashboard["Admin Dashboard"]:::frontend
        TeamsOverview["Teams Overview"]:::frontend
        TeamPage["Team Page"]:::frontend
        TeamMarketsList["Team Markets List"]:::frontend
        SpecificMarket["Specific Market"]:::frontend
    end

    subgraph "Frontend: UI Components"
        direction TB
        Header["Header"]:::frontend
        Footer["Footer"]:::frontend
        ConnectWalletButton["Connect Wallet Button"]:::frontend
        MarketCard["Market Card"]:::frontend
        OrderBook["Order Book"]:::frontend
        PlaceOrderForm["Place Order Form"]:::frontend
        TeamCard["Team Card"]:::frontend
        UIPrimitives["UI Primitives"]:::frontend
    end

    subgraph "Frontend: Hooks"
        direction TB
        useWallet["useWallet"]:::frontend
        useMarkets["useMarkets"]:::frontend
        useTeams["useTeams"]:::frontend
    end

    FrontendApp --> HomePage
    FrontendApp --> MarketsList
    FrontendApp --> CreateMarket
    FrontendApp --> Profile
    FrontendApp --> TeamManagerDashboard
    FrontendApp --> AdminDashboard
    FrontendApp --> TeamsOverview
    FrontendApp --> TeamPage
    FrontendApp --> TeamMarketsList
    FrontendApp --> SpecificMarket

    FrontendApp --> Header
    FrontendApp --> Footer
    FrontendApp --> ConnectWalletButton
    FrontendApp --> MarketCard
    FrontendApp --> OrderBook
    FrontendApp --> PlaceOrderForm
    FrontendApp --> TeamCard
    FrontendApp --> UIPrimitives

    FrontendApp --> useWallet
    FrontendApp --> useMarkets
    FrontendApp --> useTeams

    %% Ethers.js Interface & Helpers
    subgraph "Ethers.js Interface & Utils"
        direction TB
        ContractAbstraction["contract.ts"]:::frontend
        Helpers["helpers.ts"]:::frontend
        Utils["utils.ts"]:::frontend
    end

    useWallet --> ContractAbstraction
    useMarkets --> ContractAbstraction
    useTeams --> ContractAbstraction
    ContractAbstraction --> Helpers
    ContractAbstraction --> Utils

    %% Wallet Provider
    WalletProvider["Web3 Wallet (MetaMask)"]:::external
    FrontendApp -->|"Web3 injection"| WalletProvider

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        direction TB
        subgraph "Smart Contract: Pepper.sol"
            direction TB
            RBAC["RBAC Module"]:::blockchain
            MarketFactory["Market Factory"]:::blockchain
            MatchingEngine["Matching Engine"]:::blockchain
            Resolution["Resolution Logic"]:::blockchain
            FeeLogic["Fee Logic"]:::blockchain
        end
        OnChainState[(On-Chain State)]:::blockchain
    end

    WalletProvider -->|"JSON-RPC"| RBAC
    WalletProvider -->|"JSON-RPC"| MarketFactory
    WalletProvider -->|"JSON-RPC"| MatchingEngine
    WalletProvider -->|"JSON-RPC"| Resolution
    WalletProvider -->|"JSON-RPC"| FeeLogic

    RBAC --> OnChainState
    MarketFactory --> OnChainState
    MatchingEngine --> OnChainState
    Resolution --> OnChainState
    FeeLogic --> OnChainState

    %% Deployment Script
    DeployScript["scripts/deploy.js"]:::script
    DeployScript --> PepperDeploy["Pepper.sol"]:::blockchain
    PepperDeploy --> OnChainState

    %% External Services
    ExternalAPI["Sports Data API"]:::external
    FrontendApp -->|"HTTP"| ExternalAPI

    %% Click Events
    click HomePage "https://github.com/jainsamyak15/pepper/blob/main/src/app/page.tsx"
    click MarketsList "https://github.com/jainsamyak15/pepper/blob/main/src/app/markets/page.tsx"
    click CreateMarket "https://github.com/jainsamyak15/pepper/blob/main/src/app/create-market/page.tsx"
    click Profile "https://github.com/jainsamyak15/pepper/blob/main/src/app/profile/page.tsx"
    click TeamManagerDashboard "https://github.com/jainsamyak15/pepper/blob/main/src/app/team-manager/page.tsx"
    click AdminDashboard "https://github.com/jainsamyak15/pepper/blob/main/src/app/admin/dashboard/page.tsx"
    click TeamsOverview "https://github.com/jainsamyak15/pepper/blob/main/src/app/teams/page.tsx"
    click TeamPage "https://github.com/jainsamyak15/pepper/blob/main/src/app/teams/[teamId]/page.tsx"
    click TeamMarketsList "https://github.com/jainsamyak15/pepper/blob/main/src/app/teams/[teamId]/markets/page.tsx"
    click SpecificMarket "https://github.com/jainsamyak15/pepper/blob/main/src/app/teams/[teamId]/markets/[marketId]/page.tsx"
    click Header "https://github.com/jainsamyak15/pepper/blob/main/src/components/Header.tsx"
    click Footer "https://github.com/jainsamyak15/pepper/blob/main/src/components/Footer.tsx"
    click ConnectWalletButton "https://github.com/jainsamyak15/pepper/blob/main/src/components/ConnectWalletButton.tsx"
    click MarketCard "https://github.com/jainsamyak15/pepper/blob/main/src/components/MarketCard.tsx"
    click OrderBook "https://github.com/jainsamyak15/pepper/blob/main/src/components/OrderBook.tsx"
    click PlaceOrderForm "https://github.com/jainsamyak15/pepper/blob/main/src/components/PlaceOrderForm.tsx"
    click TeamCard "https://github.com/jainsamyak15/pepper/blob/main/src/components/TeamCard.tsx"
    click UIPrimitives "https://github.com/jainsamyak15/pepper/tree/main/src/components/ui"
    click useWallet "https://github.com/jainsamyak15/pepper/blob/main/src/hooks/useWallet.ts"
    click useMarkets "https://github.com/jainsamyak15/pepper/blob/main/src/hooks/useMarkets.ts"
    click useTeams "https://github.com/jainsamyak15/pepper/blob/main/src/hooks/useTeams.ts"
    click ContractAbstraction "https://github.com/jainsamyak15/pepper/blob/main/src/utils/contract.ts"
    click Helpers "https://github.com/jainsamyak15/pepper/blob/main/src/utils/helpers.ts"
    click Utils "https://github.com/jainsamyak15/pepper/blob/main/src/lib/utils.ts"
    click DeployScript "https://github.com/jainsamyak15/pepper/blob/main/scripts/deploy.js"

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#0366d6,stroke-width:1px
    classDef blockchain fill:#d1e7dd,stroke:#0f5132,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#bf360c,stroke-width:1px
    classDef script fill:#e2e3e5,stroke:#495057,stroke-width:1px
```
