game-marathon/README.md

# Game Marathon

A web application for running gaming marathons with friends. Spin the wheel, complete challenges, earn points!

## Features

- Create private marathons and invite friends
- Add games with download links
- AI-generated challenges using GPT
- Spin the wheel for random game + challenge
- Points system with streak bonuses
- Leaderboard and activity feed
- Proof upload for completed challenges

## Tech Stack

- **Frontend**: React 18, TypeScript, Vite, Tailwind CSS, Zustand
- **Backend**: FastAPI, SQLAlchemy, PostgreSQL
- **AI**: OpenAI GPT-4o-mini
- **Infrastructure**: Docker, Nginx

## Quick Start

### Prerequisites

- Docker and Docker Compose
- OpenAI API key

### Setup

1. Clone the repository:
```bash
cd WebApp
```

2. Create `.env` file:
```bash
cp .env.example .env
```

3. Edit `.env` and set your values:
```env
DB_PASSWORD=your_secure_password
SECRET_KEY=your_jwt_secret_at_least_32_characters
OPENAI_API_KEY=sk-your-openai-key
```

4. Start with Docker:
```bash
docker-compose up -d
```

5. Open http://localhost in your browser

### Development Mode

**Backend:**
```bash
cd backend
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
uvicorn app.main:app --reload
```

**Frontend:**
```bash
cd frontend
npm install
npm run dev
```

## Project Structure

```
WebApp/
├── backend/           # FastAPI application
│   ├── app/
│   │   ├── api/       # API endpoints
│   │   ├── models/    # SQLAlchemy models
│   │   ├── schemas/   # Pydantic schemas
│   │   ├── services/  # Business logic
│   │   └── core/      # Config, security
│   └── uploads/       # Uploaded files
├── frontend/          # React application
│   └── src/
│       ├── api/       # API client
│       ├── components/# UI components
│       ├── pages/     # Page components
│       ├── store/     # Zustand store
│       └── types/     # TypeScript types
├── bot/               # Telegram bot (coming soon)
├── docker-compose.yml
└── nginx.conf
```

## API Documentation

When backend is running, visit:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## How to Play

1. **Create Marathon** - Set title, description, and duration
2. **Invite Friends** - Share the invite code
3. **Add Games** - Everyone adds their favorite games
4. **Generate Challenges** - AI creates challenges for each game
5. **Start Marathon** - Begin the competition
6. **Spin & Play** - Spin the wheel, get a challenge, complete it
7. **Upload Proof** - Submit screenshot/video as evidence
8. **Earn Points** - Build streaks for bonus points!

## Point System

| Difficulty | Base Points |
|------------|-------------|
| Easy       | 30-50       |
| Medium     | 60-100      |
| Hard       | 120-200     |

**Streak Bonus:**
- 2 in a row: +10%
- 3 in a row: +20%
- 4 in a row: +30%
- 5+ in a row: +40%

**Drop Penalties:**
- 1st drop: Free (streak resets)
- 2nd drop: -10 points
- 3rd drop: -25 points
- 4th+ drop: -50 points

## License

MIT