Init.

README.md

@@ -0,0 +1,196 @@
+# 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