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

cd /mnt/NV2/Development/strat-gameplay-webapp

2. Backend Setup

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:

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

# 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)

# 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

# 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

# Check running containers
docker ps

# View Redis logs
cd backend
docker compose logs redis

# Stop Redis
docker compose down

Database

# 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:

uv sync  # Reinstall all dependencies

Import errors / Module not found

Ensure dependencies are installed:

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! ⚾