strat-gameplay-webapp/QUICKSTART.md

# Paper Dynasty - Quick Start Guide

**Last Updated**: 2025-11-04

## Prerequisites

- Python 3.13+
- Node.js 18+ (for frontends)
- Docker with Compose V2
- Access to PostgreSQL server (10.10.0.42:5432)
- Git

## Initial Setup (One-Time)

### 1. Clone and Navigate
```bash
cd /mnt/NV2/Development/strat-gameplay-webapp
```

### 2. Backend Setup

```bash
cd backend

# Install UV (modern Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env and set DATABASE_URL password

# Start Redis
docker compose up -d

# Verify setup
uv run python -m app.main
# Server should start at http://localhost:8000
```

### 3. Database Setup (If Not Already Created)

Connect to your PostgreSQL server via Adminer or psql and run:

```sql
CREATE DATABASE paperdynasty_dev;
CREATE USER paperdynasty WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE paperdynasty_dev TO paperdynasty;

-- Connect to paperdynasty_dev
\c paperdynasty_dev

GRANT ALL ON SCHEMA public TO paperdynasty;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO paperdynasty;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO paperdynasty;
```

## Daily Development

### Starting the Backend

```bash
# Terminal 1: Start Redis (if not running)
cd backend
docker compose up -d

# Terminal 2: Run Backend
cd backend
uv run python -m app.main
# Or: source .venv/bin/activate && python -m app.main
```

Backend will be available at:
- Main API: http://localhost:8000
- Swagger UI: http://localhost:8000/docs
- Health Check: http://localhost:8000/api/health

### Starting Frontends (When Available)

```bash
# Terminal 3: SBA League Frontend
cd frontend-sba
npm run dev
# Available at http://localhost:3000

# Terminal 4: PD League Frontend
cd frontend-pd
npm run dev
# Available at http://localhost:3001
```

## Useful Commands

### Backend

```bash
# Run tests
cd backend
uv run pytest tests/ -v

# Format code
uv run black app/ tests/

# Type checking
uv run mypy app/

# Check logs
tail -f backend/logs/app_*.log
```

### Docker

```bash
# Check running containers
docker ps

# View Redis logs
cd backend
docker compose logs redis

# Stop Redis
docker compose down
```

### Database

```bash
# Connect to database
psql postgresql://paperdynasty:PASSWORD@10.10.0.42:5432/paperdynasty_dev

# Or use Adminer web interface
# (Running on same Docker host as PostgreSQL)
```

## Troubleshooting

### "docker-compose: command not found"
Use `docker compose` (with space) not `docker-compose`

### "greenlet library required"
This should not happen with UV. If it does, run:
```bash
uv sync  # Reinstall all dependencies
```

### Import errors / Module not found
Ensure dependencies are installed:
```bash
uv sync  # Install/sync dependencies
# Or check virtual environment
source .venv/bin/activate
which python  # Should show path to .venv/bin/python
```

### Database connection errors
1. Check .env has correct DATABASE_URL with password
2. Verify database exists: `psql -h 10.10.0.42 -U paperdynasty -d paperdynasty_dev`
3. Ping database server: `ping 10.10.0.42`

### Server won't start
1. Check CORS_ORIGINS format in .env: `CORS_ORIGINS=["url1", "url2"]`
2. Ensure Redis is running: `docker ps | grep redis`
3. Check logs: `tail -f backend/logs/app_*.log`

## Project Status

✅ **Phase 1: Core Infrastructure** - COMPLETE (2025-10-21)
- Backend FastAPI server running
- PostgreSQL database configured
- WebSocket support (Socket.io)
- Health check endpoints
- JWT authentication stubs
- Redis for caching

🚧 **Next Steps**:
- Discord OAuth integration
- Frontend setup (Nuxt 3)
- Phase 2: Game Engine Core

## Key Files

- **Backend Config**: `backend/.env`
- **Backend Code**: `backend/app/`
- **Database Models**: `backend/app/models/db_models.py`
- **API Routes**: `backend/app/api/routes/`
- **WebSocket**: `backend/app/websocket/`
- **Logs**: `backend/logs/`

## Documentation

- **Main README**: `README.md`
- **Backend Details**: `backend/CLAUDE.md`
- **Environment Notes**: `.claude/ENVIRONMENT.md`
- **Implementation Plan**: `.claude/implementation/01-infrastructure.md`
- **Full PRD**: `prd-web-scorecard-1.1.md`

## Support

For issues or questions:
1. Check `backend/CLAUDE.md` for backend-specific details
2. Check `.claude/ENVIRONMENT.md` for gotchas and environment quirks
3. Review implementation plans in `.claude/implementation/`

---

**Happy Coding! ⚾**