Developer Overview
Repository structure, tech stack, and architecture diagram
Vezta is a prediction market trading terminal that aggregates markets from Polymarket and Kalshi (via DFlow on Solana) into a unified trading interface. The repository contains four independent subprojects that share a single backend API.
Repository Structure
There is no pnpm workspace at the root. Each subproject is fully independent with its own node_modules and pnpm-lock.yaml.
| Subproject | Stack | Port | Description |
|---|---|---|---|
vezta-fe/ | Next.js 16, React 19, Tailwind v4, TanStack Query v5 | 3000 | Web frontend -- App Router with Kubb code-gen from OpenAPI |
vezta-be/ | NestJS, Fastify, Prisma, PostgreSQL, Redis/BullMQ | 3001 | Backend API -- market ingestion, trading, signals, WebSockets |
vezta-mobile/ | Expo SDK 55, RN, NativeWind v4, Reanimated v4 | -- | Mobile app (planned -- code not yet in repo, designs in plans/mobile/) |
vezta-docs/ | Next.js, Fumadocs, MDX | -- | This documentation site |
Package manager is pnpm across all subprojects. Node 20+ is required (backend/frontend CI use Node 20).
Data Flow
The backend continuously ingests market data from Polymarket and DFlow (Kalshi), normalizes it into a unified schema, stores it in PostgreSQL, and serves it to clients via REST and WebSocket APIs. Redis handles caching, pub/sub for real-time delivery, and BullMQ job queues. Trading routes through exchange adapters that handle each venue's signing model.
Custody Model
| Exchange | Custody | Funding | KYC |
|---|---|---|---|
| Polymarket | Per-user Gnosis Safe (1-of-1) on Polygon, deterministic CREATE2 from a backend-managed EOA. Gasless deploy + USDC approvals via Builder Relayer. | Cross-chain USDC deposit via Polymarket Bridge | None |
| Kalshi (via DFlow) | User's own Solana wallet (Phantom, Solflare). Outcome tokens are SPL Token-2022 in their wallet. Backend only proxies quote + status calls. | Send USDC directly to user's Solana wallet | DFlow Proof KYC required for buying (free, ~2 min, Stripe Identity) |
API Contract
The backend auto-exports an openapi.json specification on startup. The frontend uses Kubb to generate TypeScript types, Zod schemas, fetch clients, and TanStack Query hooks from this spec.
After any backend API change:
cd vezta-be && pnpm export:openapi # 1. Export spec
cd vezta-fe && pnpm generate # 2. Regen frontend client
# 3. Copy vezta-be/openapi.json → vezta-docs/public/openapi.json
cd vezta-docs && pnpm generate:api # 4. Regen API reference docsNever hand-edit files in lib/api/gen/. These files are fully regenerated by code-gen tools and manual changes will be overwritten.
Environments
| Environment | Frontend | Backend |
|---|---|---|
| Local | localhost:3000 | not run locally — code changes go to staging |
| Staging | dev.vezta.io | staging.vezta.io |
| Production | vezta.io | backend.vezta.io |
Branch promotion path: dev → staging → main. dev is integration; staging is the release candidate; main is production. Each environment runs against its own backend VM and database.
Sections
Tech Stack
Detailed breakdown of all technologies used across frontend and backend.
Quickstart
Get the dev environment running on your machine.
Architecture
System overview, data model, ingestion pipelines, trading engine, signals, auth.
WebSocket Reference
Connection setup, channel subscriptions, and payload schemas.