Cal Corum 5c75b935f0 CLAUDE: Initial project setup - documentation and infrastructure

Add comprehensive project documentation and Docker infrastructure for
Paper Dynasty Real-Time Game Engine - a web-based multiplayer baseball
simulation platform replacing the legacy Google Sheets system.

Documentation Added:
- Complete PRD (Product Requirements Document)
- Project README with dual development workflows
- Implementation guide with 5-phase roadmap
- Architecture docs (backend, frontend, database, WebSocket)
- CLAUDE.md context files for each major directory

Infrastructure Added:
- Root docker-compose.yml for full stack orchestration
- Dockerfiles for backend and both frontends (multi-stage builds)
- .dockerignore files for optimal build context
- .env.example with all required configuration
- Updated .gitignore for Python, Node, Nuxt, and Docker

Project Structure:
- backend/ - FastAPI + Socket.io game engine (Python 3.11+)
- frontend-sba/ - SBA League Nuxt 3 frontend
- frontend-pd/ - PD League Nuxt 3 frontend
- .claude/implementation/ - Detailed implementation guides

Supports two development workflows:
1. Local dev (recommended): Services run natively with hot-reload
2. Full Docker: One-command stack orchestration for testing/demos

Next: Phase 1 implementation (backend/frontend foundations)

2025-10-21 16:21:13 -05:00

2.8 KiB

Raw Blame History

Authentication & Authorization System

Status: Placeholder Cross-Cutting Concern: All Phases

Overview

Discord OAuth-based authentication system with JWT session management and role-based access control for game actions.

Key Components

1. Discord OAuth Flow

Authorization Request:

https://discord.com/api/oauth2/authorize
  ?client_id={CLIENT_ID}
  &redirect_uri={REDIRECT_URI}
  &response_type=code
  &scope=identify

Token Exchange (Backend):

Receive authorization code from callback
Exchange code for access token
Fetch user profile from Discord API
Lookup/create user record
Generate JWT token
Return JWT to frontend

JWT Payload:

{
  "user_id": "discord_snowflake_id",
  "username": "DiscordUser#1234",
  "teams": [42, 99],  // Team IDs user owns
  "exp": 1735689600,  // Expiration timestamp
  "iat": 1735603200   // Issued at timestamp
}

2. Session Management

Frontend:

Store JWT in localStorage or cookie
Include JWT in WebSocket auth header
Include JWT in HTTP API requests (Authorization: Bearer)
Auto-refresh before expiration (optional)
Clear on logout

Backend:

Verify JWT signature on every request
Check expiration
Extract user_id and teams from payload
Attach to request context

3. Authorization Rules

Game Actions:

User must own the team to make decisions
Spectators have read-only access
No actions allowed after game completion

API Endpoints:

/api/games - Authenticated users only
/api/games/:id - Public if game visibility is public
/api/games/:id/join - Must own a team in the game

WebSocket Events:

All action events require team ownership validation
Spectators can only receive events, not emit actions

4. Security Considerations

Token Storage: HttpOnly cookies preferred over localStorage
Token Expiration: 24 hours, refresh after 12 hours
Rate Limiting: Per-user action limits
Logout: Invalidate token (blacklist or short expiry)
HTTPS Only: All communication encrypted

Implementation Files