Local Setup & Development Guide
Relevant source files
The following files were used as context for generating this wiki page:
- package.json
- src/app/[locale]/admin/api/event-creations/ai/route.ts
- src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx
- src/app/[locale]/admin/(general)/_actions/update-general-settings.ts/_actions/update-general-settings.ts)
- tests/unit/adminCreateEventFormUtils.test.ts
- src/app/llms.txt/route.ts
This guide provides the necessary technical information to set up, develop, and maintain the Kuest Prediction Market platform locally. The project is a decentralized prediction market built on Next.js, leveraging modern tools like Oxlint for linting, Vitest for unit testing, and Playwright for end-to-end verification.
The platform architecture is designed to handle market discovery, event-based contracts, and real-time trading data through a combination of on-chain interactions and traditional web APIs. Developers will interact with a stack including React 19, Tailwind CSS 4, and Drizzle ORM for database management.
Sources: package.json:1-125, src/app/llms.txt/route.ts:160-165
Core Prerequisites
The project requires specific runtime environments and package managers to ensure consistency across development environments.
Environment Requirements
- Node.js: Version
24.x - Package Manager:
pnpm@11.20.0
Sources: package.json:120-124
Primary Development Scripts
The following scripts are defined in the package.json for managing the local lifecycle:
| Script | Command | Description |
|---|---|---|
dev | next dev | Starts the Next.js development server. |
build | next build | Compiles the application for production. |
start | next start | Starts the production server. |
lint | oxlint . --fix | Runs Oxlint to identify and fix code quality issues. |
fmt | oxfmt | Formats code using the project's formatting rules. |
test | vitest run | Executes unit tests. |
test:e2e | playwright test | Executes end-to-end browser tests. |
db:push | node scripts/migrate.ts | Pushes local schema changes to the database. |
Sources: package.json:13-24
System Architecture Overview
The application follows a standard Next.js App Router structure with localized routes. It integrates multiple third-party services to handle AI market generation, identity verification, and cross-chain swaps.
Component Relationship Diagram
This diagram shows the relationship between the local development environment, the application core, and external integrations.
Admin Configuration & Integration Setup
Much of the platform's functionality depends on correct configuration within the Admin dashboard. Locally, these settings are persisted via the SettingsRepository.
Integration Settings
Developers must configure several keys to enable full functionality during local development:
- OpenRouter: Used for AI-driven event creation and rules generation.
- Sumsub: Enables identity verification workflows.
- LI.FI: Facilitates cross-chain deposits and swaps.
- TheSportsDB/PandaScore: Provides data for sports and esports markets.
Sources: src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx:50-100, src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:600-650
Admin Settings Update Flow
When settings are updated via the admin interface, the following sequence occurs:
Testing & Quality Assurance
The project employs a strict testing strategy combining unit tests for logic and Playwright for user flows.
Unit Testing
Unit tests are located in tests/unit/ and use Vitest. They cover critical utilities such as structured data generation, FAQ builders, and admin form validation.
- Event Validation:
adminCreateEventFormUtils.test.tsensures that market creation logic follows deterministic rules. - Structured Data:
structuredData.test.tsverifies SEO and Schema.org metadata generation. - Localization:
categoryFaq.test.tstests the interpolation of localized strings for category pages.
Sources: tests/unit/adminCreateEventFormUtils.test.ts:1-50, tests/unit/structuredData.test.ts:1-30
Local Validation Logic
During development, the AI route checks for mandatory fields before allowing market generation:
Asset Management
The platform handles images and legal documents through a specialized upload utility.
Image Processing
The application uses the sharp library for server-side image manipulation.
- Logos: Resized to
512x512and converted to PNG. - PWA Icons: Specifically resized for
192x192and512x512requirements. - Security: SVG uploads are sanitized to remove
<script>tags and other malicious vectors.
Sources: src/app/[locale]/admin/(general)/_actions/update-general-settings.ts:285-330, tests/unit/themeSiteIdentity.test.ts:40-60
Development Summary
To start developing locally:
- Ensure Node
24.xandpnpmare installed. - Run
pnpm installto fetch dependencies. - Use
pnpm db:pushto sync your local database. - Run
pnpm devto launch the platform. - Use the Admin panel at
/admin/integrationsto configure OpenRouter and other necessary API keys.
Sources: package.json:1-25, src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx:150-180