ProductClankDocs

Architecture

ProductClank Arena is built on a modern, scalable architecture combining blockchain technology with traditional web infrastructure.

Technology Stack

Frontend

  • Framework: Next.js 15 with App Router
  • Styling: Tailwind CSS with custom components
  • UI Components: Radix UI primitives
  • State Management: React Query for server state, Jotai for client state
  • Animations: Motion (Framer Motion)

Backend

  • Runtime: Next.js API Routes
  • Database: Supabase (PostgreSQL)
  • Authentication: Farcaster Frame SDK + Privy
  • File Storage: Supabase Storage

Blockchain

  • Network: Base (Ethereum L2)
  • Smart Contracts: Solidity (0.8.20+)
  • Web3 Libraries: wagmi, viem, ethers
  • Token Standard: ERC-20 (USDC)

System Architecture

Application Layers

┌─────────────────────────────────────┐
│         Frontend (Next.js)          │
│  - Web App                          │
│  - Farcaster Frames                 │
│  - Mobile-Optimized UI              │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      API Layer (Next.js API)        │
│  - REST Endpoints                   │
│  - Server Actions                   │
│  - Authentication                   │
└──────────────┬──────────────────────┘
               │
    ┌──────────┴──────────┐
    │                     │
┌───▼──────┐      ┌───────▼──────┐
│ Database │      │  Blockchain   │
│ Supabase │      │    Base       │
│          │      │               │
│ PostgreSQL│     │ Smart Contracts│
└──────────┘      └───────────────┘

Route Structure

src/app/
├── (frame)/          # Farcaster Frame interface
├── (web)/            # Traditional web interface
├── (miniapp)/        # Embedded mini app interface
├── api/              # API routes
│   ├── auction/      # Auction endpoints
│   ├── bids/         # Bidding endpoints
│   ├── campaigns/    # Campaign endpoints
│   └── products/     # Product endpoints
└── docs/             # Documentation site

Key Components

Product Management

  • Product submission and editing
  • Media upload and storage
  • Search and filtering
  • Voting ("believe") system

Campaign System

  • Campaign creation and management
  • Action item tracking
  • Reward distribution
  • Participation verification

Auction System

  • On-chain auction contract
  • Bid placement and tracking
  • Automatic settlement
  • Winner selection

Leaderboard System

  • Real-time point calculation
  • Daily snapshots
  • Weighted allocation
  • CSV export functionality

Data Flow

Product Submission Flow

  1. User submits product via frontend
  2. API validates and processes data
  3. Media uploaded to Supabase Storage
  4. Product record created in database
  5. Product appears in feed

Auction Bidding Flow

  1. User initiates bid via frontend
  2. Frontend checks USDC allowance
  3. User approves spending (if needed)
  4. Bid transaction sent to blockchain
  5. Contract validates and processes bid
  6. Database updated with bid record
  7. Previous bidder refunded (if applicable)

Security Features

  • Authentication: Farcaster + Privy wallet connection
  • Authorization: Role-based access control
  • Rate Limiting: API rate limits to prevent abuse
  • Input Validation: Server-side validation of all inputs
  • Smart Contract Security: Reentrancy guards, pausable, ownable

Performance Optimizations

  • React Query for efficient data fetching
  • Image optimization via Next.js Image
  • Database indexing for fast queries
  • Batch operations for bulk updates
  • Caching strategies for frequently accessed data