System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
- src/app/llms.txt/route.ts
- src/lib/structured-data.ts
- src/app/[locale]/admin/api/event-creations/ai/route.ts
- src/app/[locale]/admin/(general)/_actions/update-general-settings.ts/_actions/update-general-settings.ts)
- src/app/[locale]/(platform)/event/[slug]/_components/DirectResolutionButton.tsx/event/[slug]/_components/DirectResolutionButton.tsx)
- src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx
The system architecture of the prediction market platform is a multi-tier decentralized application designed to facilitate real-world event trading. It integrates a Next.js frontend with various blockchain protocols (primarily Polygon), centralized data APIs (Gamma, CLOB, and Data APIs), and AI-driven services for market creation and validation. The architecture prioritizes non-custodial asset management, allowing users to interact with event-based contracts through self-hosted or embedded wallets.
The platform's core infrastructure is divided into public-facing interfaces, an administrative suite for market management, and a robust integration layer that connects to external oracles, liquidity aggregators, and identity verification services.
Core Component Hierarchy
The system is structured around several primary service endpoints that handle different aspects of the market lifecycle, from discovery to trade execution.
Visual representation of the primary communication flows between the frontend and external/on-chain services. Sources: src/app/llms.txt/route.ts:108-132
Primary Service Endpoints
| Service | Function | Endpoint Source |
|---|---|---|
| Gamma API | Market discovery, events, tags, and search metadata. | publicRuntimeEnv.gammaUrl |
| CLOB API | Order matching, cancellations, and order book pricing. | publicRuntimeEnv.clobUrl |
| Data API | User positions, activity, leaderboards, and analytics. | publicRuntimeEnv.dataUrl |
| CLOB WebSocket | Real-time market and user data streams. | publicRuntimeEnv.wsClobUrl |
| OpenRouter | AI-generated market rules and content validation. | openRouterSettings.apiKey |
Sources: src/app/llms.txt/route.ts:108-132, src/app/[locale]/admin/api/event-creations/ai/route.ts:581-600
Market Creation & AI Validation Flow
The administrative architecture utilizes AI via OpenRouter to automate and validate the creation of prediction markets. This process ensures that market rules are objective, deterministic, and follow specific formatting standards.
Sequence diagram showing the automated rule generation process using external market samples and LLM processing. Sources: src/app/[locale]/admin/api/event-creations/ai/route.ts:585-680
Validation Mechanisms
The system performs both local and AI-driven checks during event creation:
- Mandatory Checks: Validates required fields such as title, end date, and minimum sub-categories (at least 4). Sources: src/app/[locale]/admin/api/event-creations/ai/route.ts:400-430
- AI Content Validation: Uses LLMs to detect language errors, deterministic logic issues, and adherence to safety guidelines (rejecting content encouraging harm). Sources: src/app/[locale]/admin/api/event-creations/ai/route.ts:805-830
- Rule Formatting: Applies logic to repair punctuation spacing and strip internal field references (e.g., removing technical terms like
marketModefrom user-facing rules). Sources: src/app/[locale]/admin/api/event-creations/ai/route.ts:250-320
On-Chain Resolution Architecture
Resolution is handled through a combination of decentralized oracles (UMA) and direct resolution mechanisms. The system supports a "propose-and-resolve" flow where eligible actors can submit outcomes to the blockchain.
Direct Resolution Component
The DirectResolutionButton manages the complex state transitions required for submitting market outcomes. It handles permissions via a Proposer Whitelist and manages the financial "bond" required for proposing rewards.
Flow of the resolution submission process, distinguishing between whitelisted admins and general proposers. Sources: src/app/[locale]/(platform)/event/[slug]/_components/DirectResolutionButton.tsx:850-1050
Smart Contract Interactions
The resolution layer interacts with several key contracts:
- Direct Resolution Oracle: Handles
proposeAndResolveandproposeAndResolveNegRiskcalls. Sources: src/app/[locale]/(platform)/event/[slug]/_components/DirectResolutionButton.tsx:1060-1080 - Resolution Rewards: Manages
submitProposalwith USDC bonds and reward distributions. Sources: src/app/[locale]/(platform)/event/[slug]/_components/DirectResolutionButton.tsx:945-965 - CTF Adapter: Stores question metadata and resolution status. Sources: src/app/[locale]/(platform)/event/[slug]/_components/DirectResolutionButton.tsx:780-800
Integration & Extension Layer
The system features a centralized integration management module that allows administrators to configure third-party services.
| Integration | Purpose | Implementation Detail |
|---|---|---|
| Sumsub | Identity verification (KYC). | Configures app tokens, secret keys, and enforcement levels. |
| LI.FI | Cross-chain swaps and deposits. | Handles integrator IDs and API keys for liquidity routing. |
| PandaScore / TheSportsDB | Sports/Esports data. | Imports schedules, teams, and scores via API keys. |
| Polymarket | Arbitrage & Mirrored Markets. | Enables separate wallets for cross-platform trading. |
| Custom JS | Analytics & Support Tools. | Allows injecting script snippets on specific routes. |
Sources: src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx:100-450
Data Modeling & SEO Metadata
The platform implements structured data (JSON-LD) to improve search engine visibility and provide machine-readable event context.
Structured Data Construction
The buildEventStructuredData function aggregates data from multiple sources to create a Schema.org Event object:
- Site Identity: Provides organization name, logo, and social links (
sameAs). Sources: src/lib/structured-data.ts:160-190 - Event Context: Extracts start/end dates, resolution status, and images. Sources: src/lib/structured-data.ts:200-240
- Breadcrumbs: Dynamically generates paths based on market categories or sports verticals. Sources: src/lib/structured-data.ts:108-150
- FAQ: Generates
FAQPageentities from event-specific rules and common questions. Sources: src/lib/structured-data.ts:21-35
Conclusion
The architecture represents a hybrid approach where a centralized Next.js/API layer manages user experience, AI automation, and SEO, while the critical financial logic (trading and resolution) is offloaded to decentralized protocols and CLOB infrastructures. This separation allows for rapid iteration of the interface and AI features without compromising the trustless nature of the underlying prediction market contracts.