197 lines
4.6 KiB
Markdown
197 lines
4.6 KiB
Markdown
# 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 with Docker
|
|
|
|
```bash
|
|
# Start all services
|
|
docker-compose 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.
|
|
|
|
## 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
|