HUNCH Architecture Documentation

System Overview

HUNCH is a decentralized prediction markets platform built with a modern web3 architecture that combines frontend React application, Supabase backend services, and Ethereum smart contracts.

High-Level Architecture

graph TB
    subgraph "User Layer"
        U1[Web Users]
        U2[Mobile Users]
        U3[API Users]
    end
    
    subgraph "Frontend Layer"
        FE[React Frontend]
        WC[Web3 Connectors]
        UI[UI Components]
    end
    
    subgraph "Backend Layer"
        SB[Supabase]
        DB[(PostgreSQL)]
        EF[Edge Functions]
        RT[Realtime]
    end
    
    subgraph "Blockchain Layer"
        SC[Smart Contracts]
        ETH[Ethereum Network]
        POL[Polygon Network]
    end
    
    subgraph "External Services"
        WCP[WalletConnect]
        IF[Infura/Alchemy]
        OR[Oracle Services]
    end
    
    U1 --> FE
    U2 --> FE
    U3 --> SB
    
    FE --> WC
    FE --> UI
    FE --> SB
    
    WC --> SC
    SC --> ETH
    SC --> POL
    
    SB --> DB
    SB --> EF
    SB --> RT
    
    WC --> WCP
    SC --> IF
    EF --> OR

Component Architecture

Frontend Architecture

graph TD
    subgraph "React Application"
        APP[App.tsx]
        
        subgraph "Pages"
            IDX[Index]
            MKT[Market Detail]
            PRT[Portfolio]
            PRF[Profile]
        end
        
        subgraph "Components"
            MC[Market Card]
            TP[Trading Panel]
            NAV[Navigation]
            WC[Wallet Connection]
        end
        
        subgraph "Hooks"
            UM[useMarkets]
            UT[useTrading]
            UW[useWallet]
            UE[useEnhanced]
        end
        
        subgraph "Services"
            TS[Trading Service]
            MS[Market Service]
            NS[Notification Service]
        end
        
        subgraph "State Management"
            RQ[React Query]
            WG[Wagmi]
            CTX[React Context]
        end
    end
    
    APP --> IDX
    APP --> MKT
    APP --> PRT
    APP --> PRF
    
    IDX --> MC
    MKT --> TP
    APP --> NAV
    APP --> WC
    
    MC --> UM
    TP --> UT
    WC --> UW
    MKT --> UE
    
    UM --> MS
    UT --> TS
    UW --> NS
    
    MS --> RQ
    TS --> WG
    NS --> CTX

Smart Contract Architecture

graph TB
    subgraph "Core Contracts"
        MF[MarketFactory]
        M[Market]
        OR[Oracle]
        MOMF[MultiOptionMarketFactory]
        MOM[MultiOptionMarket]
    end
    
    subgraph "Market Types"
        BM[Binary Markets]
        MM[Multi-Option Markets]
    end
    
    subgraph "External Dependencies"
        OZ[OpenZeppelin Libraries]
        RE[ReentrancyGuard]
        OW[Ownable]
    end
    
    MF -->|creates| M
    MOMF -->|creates| MOM
    M -->|resolves via| OR
    MOM -->|resolves via| OR
    
    M --> BM
    MOM --> MM
    
    M --> OZ
    MOM --> OZ
    OR --> OZ
    
    OZ --> RE
    OZ --> OW

Data Flow Architecture

Trading Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Wallet
    participant Contract
    participant Database
    participant Oracle
    
    User->>Frontend: Initiate Trade
    Frontend->>Wallet: Request Transaction
    Wallet->>User: Confirm Transaction
    User->>Wallet: Approve
    Wallet->>Contract: Execute buyShares()
    Contract->>Contract: Update AMM Prices
    Contract->>Frontend: Transaction Receipt
    Frontend->>Database: Update Trade History
    Frontend->>User: Show Success
    
    Note over Oracle: For Market Resolution
    Oracle->>Contract: resolveMarket()
    Contract->>Contract: Set Winning Outcome
    Contract->>Frontend: Market Resolved Event
    Frontend->>Database: Update Market Status
    Frontend->>User: Show Resolution

Market Creation Flow

sequenceDiagram
    participant Creator
    participant Frontend
    participant Wallet
    participant Factory
    participant Market
    participant Database
    
    Creator->>Frontend: Fill Market Form
    Frontend->>Frontend: Validate Input
    Frontend->>Wallet: Request Creation TX
    Wallet->>Factory: createMarket()
    Factory->>Market: Deploy New Contract
    Market->>Factory: Return Address
    Factory->>Frontend: Market Created Event
    Frontend->>Database: Store Market Metadata
    Frontend->>Creator: Show Success

Database Schema

Core Tables

erDiagram
    markets_enhanced {
        uuid id PK
        text market_id UK
        text question
        text description
        text category
        text market_type
        text creator_address
        timestamp end_time
        boolean resolved
        integer winning_option_index
        bigint total_volume
        timestamp created_at
        timestamp updated_at
    }
    
    market_options {
        uuid id PK
        text market_id FK
        integer option_index
        text option_text
        bigint shares_outstanding
        bigint total_volume
        bigint current_price
        timestamp created_at
        timestamp updated_at
    }
    
    x_connections {
        uuid id PK
        text user_address UK
        text x_user_id
        text x_username
        text x_display_name
        text x_profile_image_url
        integer x_follower_count
        boolean x_verified
        text access_token
        text access_token_secret
        timestamp created_at
        timestamp updated_at
    }
    
    markets_enhanced ||--o{ market_options : has

Network Architecture

Supported Networks

graph TD
    subgraph "Mainnet Networks"
        ETH[Ethereum Mainnet]
        POL[Polygon Mainnet]
    end
    
    subgraph "Testnet Networks"
        SEP[Sepolia Testnet]
        MUM[Mumbai Testnet]
    end
    
    subgraph "Contract Addresses"
        MF_ETH[MarketFactory: 0x...]
        OR_ETH[Oracle: 0x...]
        MF_POL[MarketFactory: 0x...]
        OR_POL[Oracle: 0x...]
    end
    
    ETH --> MF_ETH
    ETH --> OR_ETH
    POL --> MF_POL
    POL --> OR_POL
    
    SEP --> MF_ETH
    MUM --> MF_POL

Security Architecture

Access Control

graph TD
    subgraph "Smart Contract Access"
        OWNER[Contract Owner]
        RESOLVER[Oracle Resolver]
        USER[Regular User]
    end
    
    subgraph "Database Access"
        ANON[Anonymous Access]
        AUTH[Authenticated User]
        ADMIN[Admin User]
    end
    
    subgraph "Frontend Access"
        GUEST[Guest User]
        CONNECTED[Connected Wallet]
        VERIFIED[Verified User]
    end
    
    OWNER -->|can| PAUSE[Pause Contracts]
    OWNER -->|can| UPGRADE[Upgrade Contracts]
    RESOLVER -->|can| RESOLVE[Resolve Markets]
    USER -->|can| TRADE[Trade Shares]
    
    ANON -->|can| READ[Read Public Data]
    AUTH -->|can| WRITE[Write User Data]
    ADMIN -->|can| MANAGE[Manage Platform]
    
    GUEST -->|can| VIEW[View Markets]
    CONNECTED -->|can| CREATE[Create Markets]
    VERIFIED -->|can| SOCIAL[Social Features]

Security Layers

graph TB
    subgraph "Frontend Security"
        CSP[Content Security Policy]
        CORS[CORS Headers]
        INPUT[Input Validation]
    end
    
    subgraph "API Security"
        RLS[Row Level Security]
        RATE[Rate Limiting]
        AUTH[JWT Authentication]
    end
    
    subgraph "Smart Contract Security"
        REEN[Reentrancy Guards]
        ACCESS[Access Control]
        PAUSE[Emergency Pause]
    end
    
    subgraph "Infrastructure Security"
        HTTPS[HTTPS Only]
        ENV[Environment Variables]
        AUDIT[Security Audits]
    end
    
    CSP --> INPUT
    CORS --> RLS
    INPUT --> RATE
    
    RLS --> AUTH
    RATE --> REEN
    AUTH --> ACCESS
    
    REEN --> PAUSE
    ACCESS --> HTTPS
    PAUSE --> ENV
    
    HTTPS --> AUDIT

Performance Architecture

Caching Strategy

graph TD
    subgraph "Frontend Caching"
        QC[React Query Cache]
        BC[Browser Cache]
        SW[Service Worker]
    end
    
    subgraph "API Caching"
        CDN[CDN Cache]
        DB_CACHE[Database Cache]
        REDIS[Redis Cache]
    end
    
    subgraph "Blockchain Caching"
        RPC[RPC Node Cache]
        INDEXER[Indexer Cache]
        EVENT[Event Cache]
    end
    
    QC -->|30s TTL| API_DATA[API Data]
    BC -->|1hr TTL| STATIC[Static Assets]
    SW -->|Offline| CACHED_PAGES[Cached Pages]
    
    CDN -->|1hr TTL| RESPONSES[API Responses]
    DB_CACHE -->|5min TTL| QUERIES[Query Results]
    REDIS -->|15min TTL| SESSIONS[User Sessions]
    
    RPC -->|Block TTL| BLOCKCHAIN_DATA[Blockchain Data]
    INDEXER -->|Real-time| EVENTS[Contract Events]
    EVENT -->|Permanent| HISTORICAL[Historical Data]

Load Balancing

graph TD
    subgraph "Users"
        U1[User 1]
        U2[User 2]
        U3[User N]
    end
    
    subgraph "CDN Layer"
        CF[Cloudflare]
    end
    
    subgraph "Application Layer"
        LB[Load Balancer]
        APP1[App Instance 1]
        APP2[App Instance 2]
        APP3[App Instance N]
    end
    
    subgraph "Database Layer"
        PG_PRIMARY[PostgreSQL Primary]
        PG_REPLICA[PostgreSQL Replica]
    end
    
    subgraph "Blockchain Layer"
        RPC1[RPC Node 1]
        RPC2[RPC Node 2]
        RPC3[RPC Node N]
    end
    
    U1 --> CF
    U2 --> CF
    U3 --> CF
    
    CF --> LB
    
    LB --> APP1
    LB --> APP2
    LB --> APP3
    
    APP1 --> PG_PRIMARY
    APP2 --> PG_REPLICA
    APP3 --> PG_REPLICA
    
    APP1 --> RPC1
    APP2 --> RPC2
    APP3 --> RPC3

Scalability Architecture

Horizontal Scaling

graph TD
    subgraph "Auto-Scaling Groups"
        ASG[Application Auto Scaling]
        DB_SCALE[Database Scaling]
        FUNC_SCALE[Function Scaling]
    end
    
    subgraph "Scaling Triggers"
        CPU[CPU Usage > 70%]
        MEM[Memory Usage > 80%]
        REQ[Request Count > 1000/min]
        CONN[DB Connections > 80%]
    end
    
    subgraph "Scaling Actions"
        ADD_INSTANCE[Add App Instance]
        ADD_REPLICA[Add DB Replica]
        ADD_FUNCTION[Scale Functions]
    end
    
    CPU --> ASG
    MEM --> ASG
    REQ --> ASG
    CONN --> DB_SCALE
    
    ASG --> ADD_INSTANCE
    DB_SCALE --> ADD_REPLICA
    FUNC_SCALE --> ADD_FUNCTION

Monitoring Architecture

Observability Stack

graph TD
    subgraph "Metrics Collection"
        PROM[Prometheus]
        GRAF[Grafana]
        ALERT[AlertManager]
    end
    
    subgraph "Logging"
        LOG_AGG[Log Aggregation]
        SEARCH[Log Search]
        ANALYSIS[Log Analysis]
    end
    
    subgraph "Tracing"
        TRACE[Distributed Tracing]
        SPAN[Span Collection]
        PERF[Performance Analysis]
    end
    
    subgraph "Error Tracking"
        SENTRY[Sentry]
        ERROR_AGG[Error Aggregation]
        NOTIFY[Error Notifications]
    end
    
    PROM --> GRAF
    GRAF --> ALERT
    
    LOG_AGG --> SEARCH
    SEARCH --> ANALYSIS
    
    TRACE --> SPAN
    SPAN --> PERF
    
    SENTRY --> ERROR_AGG
    ERROR_AGG --> NOTIFY

Deployment Architecture

Multi-Environment Setup

graph TD
    subgraph "Development"
        DEV_FE[Frontend Dev]
        DEV_DB[Supabase Dev]
        DEV_SC[Sepolia Testnet]
    end
    
    subgraph "Staging"
        STAGE_FE[Frontend Staging]
        STAGE_DB[Supabase Staging]
        STAGE_SC[Mumbai Testnet]
    end
    
    subgraph "Production"
        PROD_FE[Frontend Production]
        PROD_DB[Supabase Production]
        PROD_SC[Mainnet/Polygon]
    end
    
    subgraph "CI/CD Pipeline"
        GIT[Git Repository]
        BUILD[Build Process]
        TEST[Test Suite]
        DEPLOY[Deployment]
    end
    
    GIT --> BUILD
    BUILD --> TEST
    TEST --> DEV_FE
    TEST --> STAGE_FE
    TEST --> PROD_FE
    
    DEV_FE --> DEV_DB
    DEV_FE --> DEV_SC
    
    STAGE_FE --> STAGE_DB
    STAGE_FE --> STAGE_SC
    
    PROD_FE --> PROD_DB
    PROD_FE --> PROD_SC

Integration Architecture

External Service Integration

graph TD
    subgraph "HUNCH Core"
        CORE[HUNCH Platform]
    end
    
    subgraph "Web3 Services"
        WC_CLOUD[WalletConnect Cloud]
        INFURA[Infura/Alchemy]
        ETHERSCAN[Etherscan API]
    end
    
    subgraph "Social Services"
        TWITTER[Twitter API]
        DISCORD[Discord Webhooks]
    end
    
    subgraph "Analytics Services"
        GA[Google Analytics]
        MIXPANEL[Mixpanel]
        SENTRY_EXT[Sentry]
    end
    
    subgraph "Infrastructure Services"
        VERCEL[Vercel/Netlify]
        SUPABASE_EXT[Supabase]
        CLOUDFLARE[Cloudflare]
    end
    
    CORE --> WC_CLOUD
    CORE --> INFURA
    CORE --> ETHERSCAN
    
    CORE --> TWITTER
    CORE --> DISCORD
    
    CORE --> GA
    CORE --> MIXPANEL
    CORE --> SENTRY_EXT
    
    CORE --> VERCEL
    CORE --> SUPABASE_EXT
    CORE --> CLOUDFLARE

This architecture documentation provides a comprehensive view of HUNCH's system design, showing how all components work together to create a scalable, secure, and performant prediction markets platform.