System Architecture

Kuest is built on a modern, serverless architecture that combines Next.js App Router, Polygon blockchain, and Supabase for a scalable, production-ready prediction market platform.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     User Interface Layer                     │
│  Next.js 16 App Router • Server Components • React 19       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  • Trading Logic        • Portfolio Management               │
│  • Order Execution      • Market Data                        │
│  • Authentication       • Admin Operations                   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────┬──────────────────┬──────────────────────┐
│   Blockchain     │   Database       │   External APIs      │
│   (Polygon)      │   (Supabase)     │   (Kuest CLOB)       │
├──────────────────┼──────────────────┼──────────────────────┤
│ • CTF Contracts  │ • PostgreSQL     │ • Order Matching     │
│ • Exchange       │ • Events         │ • Market Data        │
│ • USDC Token     │ • Orders         │ • Price Feeds        │
│ • UMA Oracles    │ • Users          │ • Trading History    │
│ • Safe Wallets   │ • Bookmarks      │                      │
└──────────────────┴──────────────────┴──────────────────────┘

Tech Stack

Frontend Framework

Next.js 16

App Router with Server Components, Server Actions, and Parallel Routes for optimal performance

React 19

Latest React features with Suspense, Transitions, and Server Components

TypeScript

Full type safety across the entire application

Tailwind CSS 4

Utility-first CSS with custom theme configuration

Blockchain Layer (Polygon)

Kuest currently runs on Polygon Amoy testnet with mainnet deployment coming soon. All contracts and infrastructure are production-ready.

Smart Contracts

Contract	Address	Purpose
Conditional Tokens	`0x4682...A9C7`	ERC-1155 tokens representing YES/NO outcomes
CTF Exchange	`0xB559...61cb`	Standard binary markets order matching
Neg Risk Exchange	`0xef02...24F5`	Negative risk markets (e.g., “Who will NOT win?”)
UMA CTF Adapter	`0x2008...bf8`	Oracle adapter for outcome resolution
UMA Neg Risk Adapter	`0x7242...d76`	Oracle adapter for negative risk markets
USDC Token	`0x41E9...7582` (testnet)	Collateral token for trading

Blockchain Integration

// Core blockchain libraries
import { wagmi } from '@reown/appkit-adapter-wagmi'  // Wallet connection
import { viem } from 'viem'                           // Contract interactions
import { polygonAmoy } from '@reown/appkit/networks'  // Network configuration

Key Features:

Reown AppKit: WalletConnect v2 integration for MetaMask, Rainbow, Coinbase Wallet, etc.
Safe Wallet Support: Gnosis Safe integration for multi-sig wallets
EIP-712 Signatures: Gasless order signing with typed data
Contract Reads: Real-time fee rates and referral data from chain

Database Layer (Supabase)

PostgreSQL database with Drizzle ORM for type-safe queries:

Database Schema

Events
Orders
Users
Affiliates

events table stores prediction markets:

CREATE TABLE events (
  id UUID PRIMARY KEY,
  slug TEXT UNIQUE NOT NULL,
  question TEXT NOT NULL,
  description TEXT,
  condition_id TEXT NOT NULL,
  end_date TIMESTAMP,
  resolution_date TIMESTAMP,
  resolved BOOLEAN DEFAULT false,
  outcome INTEGER,
  uma_request_tx_hash TEXT,
  uma_request_log_index INTEGER,
  created_at TIMESTAMP DEFAULT NOW()
);

Stores market metadata, condition IDs for blockchain
UMA oracle tracking for resolution
Category tags and visibility settings

orders table tracks user orders:

CREATE TABLE orders (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  event_id UUID REFERENCES events(id),
  order_id TEXT NOT NULL,
  side INTEGER NOT NULL,  -- 0=BUY, 1=SELL
  outcome INTEGER NOT NULL,  -- 0=YES, 1=NO
  price DECIMAL NOT NULL,
  amount DECIMAL NOT NULL,
  filled_amount DECIMAL DEFAULT 0,
  status TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

Tracks order lifecycle: pending → filled/cancelled
Real-time PnL calculations
Order history and trade matching

users table from Better Auth:

CREATE TABLE users (
  id UUID PRIMARY KEY,
  address TEXT UNIQUE NOT NULL,  -- Ethereum address
  email TEXT,
  username TEXT UNIQUE,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Wallet-based authentication
Optional email and username
Session and verification management

affiliates table for referral tracking:

CREATE TABLE affiliates (
  id UUID PRIMARY KEY,
  code TEXT UNIQUE NOT NULL,
  user_id UUID REFERENCES users(id),
  percentage INTEGER NOT NULL,  -- Basis points
  total_volume DECIMAL DEFAULT 0,
  total_earnings DECIMAL DEFAULT 0,
  created_at TIMESTAMP DEFAULT NOW()
);

On-chain affiliate fee sharing
Volume and earnings tracking
Referral code generation

Storage

Supabase Storage: Market images, logos, and user avatars
S3-Compatible: Alternative to Supabase Storage for self-hosting

External APIs

Kuest CLOB (Central Limit Order Book)

// Trading authentication
const credentials = {
  address: process.env.KUEST_ADDRESS,
  apiKey: process.env.KUEST_API_KEY,
  apiSecret: process.env.KUEST_API_SECRET,
  passphrase: process.env.KUEST_PASSPHRASE,
}

Shared Infrastructure:

All forks connect to the same order book
Shared liquidity across all deployments
Real-time market data and price updates
Order matching and execution
Historical trades and volume

API Endpoints:

POST /orders - Place limit/market orders
DELETE /orders/:id - Cancel orders
GET /orderbook - Real-time order book
GET /markets - Market data and prices
GET /trades - Trade history

Important: All forks must authenticate with Kuest CLOB. Running an independent order matching engine requires a commercial agreement.

Component Architecture

Application Structure

src/
├── app/                    # Next.js App Router
│   ├── [locale]/          # Internationalized routes
│   │   ├── (platform)/    # Main app pages
│   │   ├── admin/         # Admin panel
│   │   └── api/           # API routes
│   └── layout.tsx         # Root layout
├── components/            # React components
│   ├── ui/               # Base UI components
│   └── docs/             # Documentation components
├── lib/                   # Core business logic
│   ├── db/               # Database queries (Drizzle)
│   ├── orders/           # Order signing and validation
│   ├── trading-auth/     # CLOB authentication
│   └── uma.ts            # UMA oracle integration
└── providers/            # React context providers

Key Components

Trading System

Order Flow:

User creates order in UI (market/limit)
Order parameters validated client-side
EIP-712 signature generated (gasless)
Order submitted to Kuest CLOB
CLOB matches order against orderbook
Settlement executed on-chain (CTF Exchange)
Database updated with order status

Files:

src/lib/orders/signing.ts - EIP-712 order signing
src/lib/orders/validation.ts - Order validation rules
src/lib/exchange.ts - Exchange contract interactions

Market Data

Data Pipeline:

Sync Jobs (/api/sync/*) run every 5 minutes
Fetch market data from Kuest CLOB
Update database with latest prices/volumes
Generate chart data and statistics
Cache results with Next.js Data Cache

Market Types:

Binary markets (YES/NO outcomes)
Negative risk markets (exclusion logic)
Recurring markets (crypto prices, Nasdaq, social metrics)
Sports markets (live events)

Files:

src/app/api/sync/ - Cron job endpoints
src/lib/db/queries/event.ts - Market queries

Authentication

Auth Flow:

User connects wallet (Reown AppKit)
Sign-in-with-Ethereum (SIWE) challenge
User signs message with wallet
Better Auth creates session
Session stored in database + cookie

Trading Authentication:Separate from web auth - encrypts CLOB credentials:

// Encrypt and store trading credentials
const encrypted = await encryptTradingCredentials({
  apiKey: userApiKey,
  apiSecret: userApiSecret,
  passphrase: userPassphrase,
})

Files:

src/lib/auth.ts - Better Auth configuration
src/lib/trading-auth/ - CLOB authentication

UMA Oracle Resolution

Resolution Process:

Market reaches end date
Admin/bot proposes outcome to UMA oracle
UMA initiates challenge period (2 hours default)
Anyone can dispute with bond
If no dispute, outcome settles
If disputed, UMA governance votes
Winning outcome pushed on-chain
Users redeem winning shares

Oracle Integration:

// Build UMA propose URL
const proposeUrl = buildUmaProposeUrl({
  uma_request_tx_hash: market.uma_request_tx_hash,
  uma_request_log_index: market.uma_request_log_index,
}, 'Kuest')  // Project name

Files:

src/lib/uma.ts - UMA URL builders
src/lib/contracts.ts - UMA adapter addresses

Data Flow

Trading Flow

Order Creation

User fills out order form (amount, price, side, outcome)

Client Validation

Validate sufficient balance, price bounds, amount limits

EIP-712 Signing

Generate typed signature (no gas required)

CLOB Submission

Submit signed order to Kuest CLOB API

Order Matching

CLOB matches against existing orders in orderbook

On-Chain Settlement

Execute matched trades on CTF Exchange contract

Database Update

Record order and fills in local database

UI Update

Real-time updates to portfolio, positions, and PnL

Market Sync Flow

┌──────────────┐
│ Vercel Cron  │  Every 5 minutes
└──────┬───────┘
       ↓
┌──────────────────────────────────┐
│  /api/sync/markets               │  Fetch market list
│  /api/sync/prices                │  Update current prices
│  /api/sync/volume                │  Sync 24h volume
│  /api/sync/orderbooks            │  Update orderbook depth
│  /api/sync/charts                │  Generate price charts
└──────┬───────────────────────────┘
       ↓
┌──────────────┐     ┌──────────────┐
│ Kuest CLOB   │────>│  Supabase    │
│  API Data    │     │   Database   │
└──────────────┘     └──────────────┘
       ↓
┌──────────────────────────────────┐
│  Next.js Data Cache (ISR)        │
│  Revalidate: 60s                 │
└──────────────────────────────────┘

Infrastructure Options

Option 1: Vercel + Supabase (Recommended)

Best for: Quick deployment, zero maintenance

Pros

One-click deployment
Automatic scaling
Built-in CDN
Integrated database
Free tier available

Cons

Vendor lock-in
Usage-based pricing
Limited customization

Components:

Vercel: Next.js hosting, serverless functions, cron jobs
Supabase: PostgreSQL, Storage, Auth (optional)
Revalidation: ISR with 60s cache

Option 2: Docker Self-Hosted

Best for: Full control, cost optimization

Pros

Complete control
Fixed costs
Custom infrastructure
No vendor lock-in

Cons

Manual maintenance
Requires DevOps knowledge
Scaling complexity

Requirements:

PostgreSQL database (self-hosted or managed)
S3-compatible storage (MinIO, AWS S3, Backblaze B2)
External cron scheduler
Reverse proxy (Nginx, Traefik)

Option 3: Kubernetes

Best for: Enterprise deployments, high availability

Pros

High availability
Auto-scaling
Multi-region support
Production-grade

Cons

Complex setup
Higher costs
K8s expertise required

Manifests provided for:

Deployment with replicas
Service and Ingress
ConfigMaps and Secrets
CronJob for sync tasks

See Deployment Options for detailed guides on each infrastructure option.

Performance Optimizations

Server-Side Rendering (SSR)

Market pages rendered on-demand
User-specific data fetched server-side
Parallel data loading with React Suspense

Incremental Static Regeneration (ISR)

// Revalidate market list every 60 seconds
export const revalidate = 60

const markets = await fetchMarkets()

Client-Side Caching

React Query for API data
Zustand for global state
LocalStorage for user preferences

Database Optimization

Indexed queries on high-traffic tables
Materialized views for complex queries
Connection pooling with Supabase

Security Considerations

Authentication

Wallet-based auth (SIWE)
Encrypted trading credentials
Session management with Better Auth
CSRF protection on mutations

API Security

Rate limiting on public endpoints
CRON_SECRET for scheduled jobs
Input validation with Zod
SQL injection prevention (Drizzle ORM)

Smart Contracts

Audited UMA oracle contracts
EIP-712 typed signatures
On-chain fee enforcement
Immutable condition IDs

Infrastructure

HTTPS only (enforced)
Environment variable encryption
Sentry error monitoring
Automated dependency updates

Scalability

Current Limits

Vercel Free Tier: 100GB bandwidth, 100 serverless function hours
Supabase Free Tier: 500MB database, 1GB storage, 2GB bandwidth
Order Rate: Limited by CLOB API rate limits

Scaling Strategies

Optimize Database Queries

Add indexes, use materialized views, implement pagination

Upgrade Infrastructure

Vercel Pro (

20/mo) + Supabase Pro (

25/mo) for higher limits

Add Caching Layers

Redis for hot data, CDN for static assets

Horizontal Scaling

Move to Kubernetes with multiple replicas and load balancing

Monitoring & Observability

Built-in Monitoring

Vercel Analytics: Traffic, performance, errors
Sentry: Error tracking and alerting
Supabase Dashboard: Database performance, query stats

Custom Metrics

// Track trading metrics
import { track } from '@vercel/analytics'

track('order_placed', {
  market: eventId,
  side: 'buy',
  outcome: 'yes',
  amount: orderAmount,
})

Next Steps

Now that you understand the architecture:

Deployment: Choose your infrastructure
Configuration: Configure advanced settings
Features: Explore platform features
API Reference: Build integrations

Get Started

Deployment

Configuration

Features

Customization

Operations

​System Architecture

​Architecture Overview

​Tech Stack

​Frontend Framework

Next.js 16

React 19

TypeScript

Tailwind CSS 4

​Blockchain Layer (Polygon)

​Smart Contracts

​Blockchain Integration

​Database Layer (Supabase)

​Database Schema

​Storage

​External APIs

​Kuest CLOB (Central Limit Order Book)

​Component Architecture

​Application Structure

​Key Components

​Data Flow

​Trading Flow

​Market Sync Flow

​Infrastructure Options

​Option 1: Vercel + Supabase (Recommended)

Pros

Cons

​Option 2: Docker Self-Hosted

Pros

Cons

​Option 3: Kubernetes

Pros

Cons

​Performance Optimizations

​Server-Side Rendering (SSR)

​Incremental Static Regeneration (ISR)

​Client-Side Caching

​Database Optimization

​Security Considerations

Authentication

API Security

Smart Contracts

Infrastructure

​Scalability

​Current Limits

​Scaling Strategies

​Monitoring & Observability

​Built-in Monitoring

​Custom Metrics

​Next Steps

Build docs developers (and LLMs) love

System Architecture

Architecture Overview

Tech Stack

Frontend Framework

Blockchain Layer (Polygon)

Smart Contracts

Blockchain Integration

Database Layer (Supabase)

Database Schema

Storage

External APIs

Kuest CLOB (Central Limit Order Book)

Component Architecture

Application Structure

Key Components

Data Flow

Trading Flow

Market Sync Flow

Infrastructure Options

Option 1: Vercel + Supabase (Recommended)

Option 2: Docker Self-Hosted

Option 3: Kubernetes

Performance Optimizations

Server-Side Rendering (SSR)

Incremental Static Regeneration (ISR)

Client-Side Caching

Database Optimization

Security Considerations

Scalability

Current Limits

Scaling Strategies

Monitoring & Observability

Built-in Monitoring

Custom Metrics

Next Steps