Paper Dynasty Real-Time Game Engine

Web-based real-time multiplayer baseball simulation platform replacing the legacy Google Sheets system.

Project Structure

strat-gameplay-webapp/
├── backend/              # FastAPI game engine
├── frontend-sba/         # SBA League Nuxt frontend
├── frontend-pd/          # PD League Nuxt frontend
├── .claude/              # Claude AI implementation guides
├── docker-compose.yml    # Full stack orchestration
└── README.md            # This file

Two Development Workflows

Option 1: Local Development (Recommended for Daily Work)

Best for: Fast hot-reload, quick iteration, debugging

Services:

• ✅ Backend runs locally (Python hot-reload)
• ✅ Frontends run locally (Nuxt hot-reload)
• ✅ Redis in Docker (lightweight)
• ✅ PostgreSQL on your existing server

Setup:

1. Environment Setup

   # Copy environment template
   cp .env.example .env
   # Edit .env with your database credentials and API keys
   

2. Start Redis (in one terminal)

   cd backend
   docker-compose up
   

3. Start Backend (in another terminal)

   cd backend
   uv run python -m app.main
   # Or manually activate: source .venv/bin/activate && python -m app.main
   

   Backend will be available at http://localhost:8000

4. Start SBA Frontend (in another terminal)

   cd frontend-sba
   npm run dev
   

   SBA frontend will be available at http://localhost:3000

5. Start PD Frontend (in another terminal)

   cd frontend-pd
   npm run dev
   

   PD frontend will be available at http://localhost:3001

Advantages:

• ⚡ Instant hot-reload on code changes
• 🐛 Easy debugging (native debuggers work)
• 💨 Fast startup times
• 🔧 Simple to restart individual services

---

Option 2: Full Docker Orchestration

Best for: Integration testing, demos, production-like environment

Services:

• ✅ Everything runs in containers
• ✅ Consistent environment
• ✅ One command to start everything

Setup:

1. Environment Setup

   # Copy environment template
   cp .env.example .env
   # Edit .env with your database credentials and API keys
   

2. Start Everything

   # From project root
   docker-compose up
   

   Or run in background:

   docker-compose up -d
   

3. View Logs

   # All services
   docker-compose logs -f
   
   # Specific service
   docker-compose logs -f backend
   docker-compose logs -f frontend-sba
   

4. Stop Everything

   docker-compose down
   

Advantages:

• 🎯 Production-like environment
• 🚀 One-command startup
• 🔄 Easy to share with team
• ✅ CI/CD ready

---

Development Commands

Backend

cd backend

# Install UV (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Run server
uv run python -m app.main

# Run tests
uv run pytest tests/ -v

# Code formatting
uv run black app/ tests/

# Linting
uv run flake8 app/ tests/

# Type checking
uv run mypy app/

Frontend

cd frontend-sba  # or frontend-pd

# Install dependencies
npm install

# Run dev server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint
npm run lint

# Type check
npm run type-check

Database Setup

This project uses an existing PostgreSQL server. You need to manually create the database:

-- On your PostgreSQL server
CREATE DATABASE paperdynasty_dev;
CREATE USER paperdynasty WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE paperdynasty_dev TO paperdynasty;

Then update DATABASE_URL in .env:

DATABASE_URL=postgresql+asyncpg://paperdynasty:your-password@your-db-server:5432/paperdynasty_dev

Environment Variables

Copy .env.example to .env and configure:

Required

• DATABASE_URL - PostgreSQL connection string
• SECRET_KEY - Application secret key (at least 32 characters)
• DISCORD_CLIENT_ID - Discord OAuth client ID
• DISCORD_CLIENT_SECRET - Discord OAuth secret
• SBA_API_URL / SBA_API_KEY - SBA League API credentials
• PD_API_URL / PD_API_KEY - PD League API credentials

Optional

• REDIS_URL - Redis connection (auto-configured in Docker)
• CORS_ORIGINS - Allowed origins (defaults to localhost:3000,3001)

---

Multi-Domain Deployment

This project supports deployment to multiple domains. Key environment variables to configure:

Backend Variables

Variable	Description	Example
FRONTEND_URL	Frontend base URL for OAuth redirects	https://yourdomain.com
DISCORD_REDIRECT_URI	Legacy Discord callback	https://yourdomain.com/auth/callback
DISCORD_SERVER_REDIRECT_URI	Server-side Discord callback	https://yourdomain.com/api/auth/discord/callback/server
CORS_ORIGINS	Allowed CORS origins (comma-separated)	https://yourdomain.com,https://api.yourdomain.com
ALLOWED_DISCORD_IDS	Whitelist of Discord user IDs	123456,789012 or empty for all

Frontend Variables

Variable	Description	Example
NUXT_PUBLIC_API_URL	Backend API base URL	https://yourdomain.com
NUXT_PUBLIC_WS_URL	WebSocket base URL	https://yourdomain.com
NUXT_PUBLIC_DISCORD_REDIRECT_URI	OAuth callback URL	https://yourdomain.com/auth/callback
NUXT_ALLOWED_HOSTS	Vite dev server allowed hosts (comma-separated)	yourdomain.com,localhost

Production Deployment

# Using Docker Compose with production overrides
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Domain Deployment Checklist

When deploying to a new domain:

1. Update Discord OAuth redirect URIs in Discord Developer Portal
2. Copy .env.example files to .env and configure all URLs
3. Update CORS_ORIGINS to include new domain
4. Add domain to NUXT_ALLOWED_HOSTS (if using dev server externally)
5. Configure reverse proxy (Nginx/NPM) to route traffic

---

Available Services

When running, the following services are available:

Service	URL	Description
Backend API	http://localhost:8000	FastAPI REST API
Backend Docs	http://localhost:8000/docs	Interactive API documentation
SBA Frontend	http://localhost:3000	SBA League web app
PD Frontend	http://localhost:3001	PD League web app
Redis	localhost:6379	Cache (not exposed via HTTP)

Health Checks

# Backend health
curl http://localhost:8000/api/health

# Or visit in browser
open http://localhost:8000/api/health

Troubleshooting

Backend won't start

• Check DATABASE_URL is correct in .env
• Verify PostgreSQL database exists
• Ensure Redis is running (docker-compose up in backend/)
• Check logs for specific errors

Frontend won't connect to backend

• Verify backend is running at http://localhost:8000
• Check CORS settings in backend .env
• Clear browser cache and cookies
• Check browser console for errors

Docker containers won't start

• Ensure .env file exists with all required variables
• Run docker-compose down then docker-compose up again
• Check docker-compose logs for specific errors
• Verify no port conflicts (8000, 3000, 3001, 6379)

Database connection fails

• Verify PostgreSQL server is accessible
• Check firewall rules allow connection
• Confirm database and user exist
• Test connection with psql directly

Documentation

• Full PRD: See /prd-web-scorecard-1.1.md
• Implementation Guide: See .claude/implementation/00-index.md
• Architecture Docs: See .claude/implementation/ directory

Tech Stack

Backend

• Framework: FastAPI (Python 3.13+)
• Package Manager: UV (modern Python package management)
• WebSocket: Socket.io
• Database: PostgreSQL 14+ with SQLAlchemy
• Cache: Redis 7
• Auth: Discord OAuth with JWT

Frontend

• Framework: Vue 3 + Nuxt 3
• Language: TypeScript
• Styling: Tailwind CSS
• State: Pinia
• WebSocket: Socket.io-client

Contributing

See .claude/implementation/ for detailed implementation guides and architecture documentation.

License

Proprietary - Paper Dynasty League System