Documentation

Getting Started

Prerequisites

  • Node.js 18 or later
  • pnpm 12 or later (recommended)
  • Git

Installation

1. Clone the Repository

git clone https://github.com/Nurtoo/fact-web.git
cd fact-web

2. Install Dependencies

pnpm install

3. Environment Configuration

cp .env.local.example .env.local

Edit .env.local and add your Privy App ID:

NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id_here

4. Start Development Server

pnpm dev

The app will be available at http://localhost:3000.

Available Scripts

ScriptDescription
pnpm devStart development server on port 3000
pnpm buildBuild for production
pnpm startStart production server on port 5001
pnpm lintRun ESLint
pnpm testRun tests with Vitest

Project Structure

fact/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes
│   ├── trade/             # Trading pages
│   ├── sports/            # Sports betting pages
│   └── page.tsx           # Home page
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   ├── trading/          # Trading components
│   └── layout/           # Layout components
├── lib/                   # Libraries and utilities
│   ├── hooks/            # Custom React hooks
│   ├── store/            # Redux store
│   └── api/              # API services
└── types/                 # TypeScript types

Features

Core Features

Real-time Trading

Live order books, trades, and price updates with WebSocket integration.

Interactive Charts

Professional K-line charts with multiple timeframes powered by Recharts.

Multi-Login Support

Email, Wallet, Google, Twitter authentication via Privy.

Dark/Light Mode

Seamless theme switching with system preference detection.

Internationalization

English and Chinese language support with easy extensibility.

Mobile Responsive

Optimized for all devices with touch-friendly interface.

Web3 Integration

Built with Wagmi and Viem for Ethereum interactions.

Sports Betting

Predict outcomes of live sports matches with real-time scores.

Trading Interface

  • Market Orders - Execute trades at current market price
  • Quick Amounts - Preset amounts for fast trading (10, 50, 100, Max)
  • Position Management - Track and close your positions
  • PnL Tracking - Real-time profit/loss calculations

Market Types

  • Cryptocurrency - Price predictions for crypto assets
  • Sports - Match outcomes and sports events
  • Hot Markets - Trending and popular markets

Authentication

  • Email Login - Passwordless email authentication
  • Wallet Connection - MetaMask, WalletConnect, and more
  • Social Login - Google, Twitter authentication
  • Embedded Wallets - For non-crypto users

API Reference

Authentication API

Login

Exchange Privy token or use Email/Password for local JWT.

POST /api/v1/auth/login

Register

Register a new user (alternative to Privy flow).

POST /api/v1/auth/register

Market API

Get Active Markets

Retrieve list of active prediction markets.

GET /api/v1/markets/active

Get Market Details

Get detailed information about a specific market.

GET /api/v1/markets/:id

Order API

Create Order

Place a new order on a market.

POST /api/v1/orders

Get User Orders

Retrieve order history for the authenticated user.

GET /api/v1/orders

WebSocket API

Price Updates

Connect to real-time price updates.

wss://your-domain.com/ws/prices

Order Book Updates

Receive real-time order book updates.

wss://your-domain.com/ws/orderbook

Error Responses

All API errors follow a consistent format:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to place this order",
    "details": {
      "required": 100,
      "available": 50
    }
  }
}

Architecture

System Overview

Fact is built as a modern web application with the following key components:

┌────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                      │
├────────────────────────────────────────────────────────────┤
│  React 18 | TypeScript | Tailwind CSS | Redux Toolkit       │
└────────────────────────────────────────────────────────────┘
                              |
                              v
┌────────────────────────────────────────────────────────────┐
│                    API Layer (Next.js API Routes)            │
├────────────────────────────────────────────────────────────┤
│  REST API | WebSocket | Authentication | Rate Limiting       │
└────────────────────────────────────────────────────────────┘
                              |
                              v
┌────────────────────────────────────────────────────────────┐
│                      Backend Services                        │
├────────────────────────────────────────────────────────────┤
│  User | Market | Order | Price | Sports                    │
└────────────────────────────────────────────────────────────┘
                              |
                              v
┌────────────────────────────────────────────────────────────┐
│                        Data Layer                            │
├────────────────────────────────────────────────────────────┤
│  PostgreSQL | Redis | WebSocket (Centrifugo)                 │
└────────────────────────────────────────────────────────────┘

Frontend Architecture

Component Structure

components/
├── ui/                    # Base UI components (shadcn/ui)
├── layout/                # Layout components (Navbar, Footer)
├── trading/               # Trading-specific components
├── market/                # Market display components
├── sports/                # Sports betting components
└── web3/                  # Web3 integration components

State Management

  • Redux Toolkit - Global application state
  • React Query - Server state management
  • Local State - Component-specific state

Backend Services

ServiceResponsibility
User ServiceAuthentication, user management
Market ServiceMarket CRUD, resolution
Order ServiceOrder execution, position management
Price ServiceReal-time price feeds
Sports ServiceSports data integration

Authentication Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    User      │     │    Privy     │     │   Backend    │
└─────────────┘     └─────────────┘     └─────────────┘
       |                    |                    |
       |  1. Login Request  |                    |
       |------------------->|                    |
       |                    |                    |
       |  2. Privy Token    |                    |
       |<-------------------|                    |
       |                    |                    |
       |  3. Exchange Token |                    |
       |--------------------------------------->|
       |                    |                    |
       |  4. JWT Token      |                    |
       |<--------------------------------------|
       |                    |                    |
       |  5. Authenticated  |                    |
       |     Requests       |                    |
       |--------------------------------------->|

Contributing

Development Setup

Prerequisites

  • Node.js 18+
  • pnpm 12+
  • Git

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork: git clone https://github.com/your-username/fact-web.git
  3. Install dependencies: pnpm install
  4. Start development server: pnpm dev

Code Style

TypeScript

  • Use TypeScript for all new code
  • Avoid any types
  • Use interfaces for object shapes

React Components

  • Use functional components with hooks
  • Use "use client" directive for client components
  • Use named exports for reusable components

Naming Conventions

TypeConventionExample
ComponentsPascalCaseMatchCard, TradingPanel
HookscamelCase + "use"useSportsData, useDebounce
ConstantsUPPER_SNAKE_CASEPAGE_SIZE, CACHE_TIMEOUT

Development Workflow

  1. Create a branch: git checkout -b feature/your-feature-name
  2. Make changes following code style guidelines
  3. Run tests: pnpm test
  4. Run linter: pnpm lint
  5. Commit changes: git commit -m "feat: add new feature description"
  6. Push and create PR

Commit Messages

Use Conventional Commits format:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Formatting
  • refactor: Code restructuring
  • test: Adding tests
  • chore: Maintenance