strat-gameplay-webapp/README.md

# 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**
   ```bash
   # Copy environment template
   cp .env.example .env
   # Edit .env with your database credentials and API keys
   ```

2. **Start Redis** (in one terminal)
   ```bash
   cd backend
   docker-compose up
   ```

3. **Start Backend** (in another terminal)
   ```bash
   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)
   ```bash
   cd frontend-sba
   npm run dev
   ```
   SBA frontend will be available at http://localhost:3000

5. **Start PD Frontend** (in another terminal)
   ```bash
   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**
   ```bash
   # Copy environment template
   cp .env.example .env
   # Edit .env with your database credentials and API keys
   ```

2. **Start Everything**
   ```bash
   # From project root
   docker-compose up
   ```

   Or run in background:
   ```bash
   docker-compose up -d
   ```

3. **View Logs**
   ```bash
   # All services
   docker-compose logs -f

   # Specific service
   docker-compose logs -f backend
   docker-compose logs -f frontend-sba
   ```

4. **Stop Everything**
   ```bash
   docker-compose down
   ```

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

---

## Development Commands

### Backend

```bash
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

```bash
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:

```sql
-- 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

```bash
# 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](https://discord.com/developers/applications)
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

```bash
# 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