h2h-prototype/README.md

# 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

```bash
# 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

```bash
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

```bash
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](LOCAL_DEVELOPMENT.md)** - Detailed guide for local development, debugging, and troubleshooting
- **[Coolify Deployment Guide](COOLIFY_DEPLOYMENT.md)** - Production deployment instructions
- **[Docker Testing Guide](DOCKER_TESTING_GUIDE.md)** - 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

```bash
cd backend
pytest
```

### Frontend Build

```bash
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