H2H - Peer-to-Peer Betting Platform MVP

A functional prototype of a peer-to-peer betting platform where users can create, accept, and settle wagers directly with other users.

Tech Stack

• Backend: FastAPI (Python 3.11+) with async SQLAlchemy ORM
• Database: SQLite (via aiosqlite) - designed for easy migration to PostgreSQL
• Frontend: React 18+ with Vite, TypeScript, TailwindCSS
• Authentication: JWT tokens with refresh mechanism
• Real-time: WebSockets for live updates
• State Management: Zustand for client state, React Query for server state

Features

• User registration and JWT-based authentication
• Virtual wallet with simulated deposits
• Create custom bets with categories, odds, and stakes
• Browse bet marketplace with filtering
• Accept bets with automatic escrow
• Settle bets with winner/loser confirmation
• Transaction history
• Real-time WebSocket updates
• Responsive UI

Quick Start

Local Development

# One-command start (recommended)
./dev.sh

# Or manually:
docker compose -f docker-compose.dev.yml up --build

# The application will be available at:
# - Frontend: http://localhost:5173
# - Backend API: http://localhost:8000
# - API Docs: http://localhost:8000/docs

Manual Setup

Backend

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
cp .env.example .env

# Initialize database and seed data
python seed_data.py

# Run development server
uvicorn app.main:app --reload

Frontend

cd frontend

# Install dependencies
npm install

# Create .env file
cp .env.example .env

# Run development server
npm run dev

Test Users

After running seed_data.py, you can login with:

• Email: alice@example.com | Password: password123
• Email: bob@example.com | Password: password123
• Email: charlie@example.com | Password: password123

Each user starts with $1000 balance.

Documentation

• Local Development Guide - Detailed guide for local development, debugging, and troubleshooting
• Coolify Deployment Guide - Production deployment instructions
• Docker Testing Guide - Testing Docker deployments

API Documentation

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Project Structure

h2h-prototype/
├── backend/
│   ├── app/
│   │   ├── models/          # SQLAlchemy models
│   │   ├── schemas/         # Pydantic schemas
│   │   ├── routers/         # API endpoints
│   │   ├── services/        # Business logic
│   │   ├── crud/            # Database operations
│   │   ├── utils/           # Security, exceptions
│   │   ├── config.py        # Configuration
│   │   ├── database.py      # Database setup
│   │   └── main.py          # FastAPI app
│   ├── data/                # SQLite database
│   ├── seed_data.py         # Test data script
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── api/             # API client
│   │   ├── components/      # React components
│   │   ├── pages/           # Page components
│   │   ├── store/           # Zustand store
│   │   ├── types/           # TypeScript types
│   │   ├── utils/           # Utilities
│   │   ├── App.tsx          # Main app
│   │   └── main.tsx         # Entry point
│   ├── package.json
│   └── vite.config.ts
└── docker-compose.yml

Core Workflows

1. Create a Bet

• User creates bet with stake, odds, and positions
• No funds are locked until bet is accepted
• Bet appears in marketplace

2. Accept a Bet

• Opponent accepts bet
• Funds from both parties locked in escrow
• Bet status changes to "matched"

3. Settle a Bet

• Either participant can declare winner
• Winner receives both stakes
• Funds released from escrow
• User stats updated

Migration to PostgreSQL

To migrate from SQLite to PostgreSQL:

1. Update DATABASE_URL in backend .env:

   DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/h2h
   

2. Update requirements.txt:

   • Remove: aiosqlite
   • Add: asyncpg

3. Run migrations (SQLAlchemy handles the rest)

Development

Backend Testing

cd backend
pytest

Frontend Build

cd frontend
npm run build

MVP Scope

In Scope:

• User auth with JWT
• Virtual wallet with simulated deposits
• Bet creation, acceptance, and settlement
• Basic escrow mechanism
• WebSocket real-time updates
• Responsive UI

Out of Scope (Future Enhancements):

• Real payment processing
• KYC/AML verification
• Blockchain integration
• Automated odds feeds
• Admin panel
• Email notifications
• Social features

License

MIT