strat-gameplay-webapp/.claude/PHASE_1_CATCHUP_PLAN.md

# Phase 1 Catch-Up Plan

**Created**: 2025-10-25
**Status**: Planning
**Reason**: Jumped ahead to Phase 2 (game engine) without completing all Phase 1 deliverables

## Current State Assessment

### ✅ What's Complete (Backend Infrastructure)

1. **Backend Foundation** ✅
   - FastAPI server with async support
   - PostgreSQL database with SQLAlchemy 2.0
   - Pydantic models for validation
   - Logging system with rotating file handlers
   - Health check endpoints (`/api/health`, `/api/health/db`)
   - CORS configuration

2. **Database Layer** ✅
   - All database models created (Game, Play, Lineup, GameSession, RosterLink, GameCardsetLink)
   - Async database operations (DatabaseOperations class)
   - Polymorphic model support (PD/SBA)
   - State persistence and recovery

3. **WebSocket Infrastructure** ✅
   - Socket.io integration with FastAPI
   - ConnectionManager class for room management
   - Basic event handlers (connect, disconnect, join_game, leave_game, heartbeat)
   - JWT token verification in connection handler

4. **Authentication Stubs** ✅
   - JWT token creation (`create_token()`)
   - JWT token verification (`verify_token()`)
   - Basic auth endpoints (`/api/auth/token`, `/api/auth/verify`)

### ⚠️ What's Incomplete/Missing

1. **Discord OAuth** - STUB ONLY
   - `/api/auth/token` endpoint exists but just creates tokens from provided data
   - No actual OAuth flow with Discord
   - No Discord API integration
   - No session management with Discord

2. **Frontend Applications** - SCAFFOLDING ONLY
   - `frontend-sba/` ✅ Nuxt 3 initialized with dependencies
   - `frontend-pd/` ✅ Nuxt 3 initialized with dependencies
   - ❌ Only bare `app.vue` - no pages, components, or logic
   - ❌ No authentication UI
   - ❌ No game creation UI
   - ❌ No gameplay UI
   - ❌ No WebSocket integration
   - ❌ No Pinia stores
   - ❌ No composables

3. **WebSocket Game Events** - BASIC ONLY
   - Only have: connect, disconnect, join_game, leave_game, heartbeat
   - Missing: game action events, state updates, error handling
   - No integration with GameEngine for real-time updates

4. **Full Auth Flow** - INCOMPLETE
   - Can create tokens, but no OAuth flow
   - No user database/storage
   - No session persistence
   - No refresh tokens

## Prioritization Strategy

### Option A: Skip Phase 1, Continue with Phase 2/3 (Recommended)
**Rationale**:
- Game engine is the core value proposition
- Can build and test game logic without frontend
- OAuth and frontend can be added later without blocking progress
- Manual testing via Python scripts works fine

**Benefits**:
- Faster time to working game engine
- Can validate game mechanics without UI complexity
- Easier to test and debug game logic

**Risks**:
- No user-facing application yet
- Can't demo to stakeholders easily

### Option B: Complete Phase 1 Fully
**Rationale**:
- Follow the original plan
- Have end-to-end system working
- Can demo to users immediately

**Benefits**:
- Complete vertical slice
- Better for early user feedback

**Risks**:
- Significant frontend work (4-6 weeks minimum)
- Delays game engine enhancements
- May build UI for features that change

### Option C: Hybrid Approach (Build Minimum Viable Frontend)
**Rationale**:
- Build just enough frontend to test game flows
- Skip Discord OAuth, use simple token auth
- Single-page app instead of full Nuxt setup

**Benefits**:
- Can see game in action
- Minimal frontend work (1-2 weeks)
- Unblocks user testing

## Recommended Plan: **Option A** (Skip Phase 1, Continue Phase 2/3)

### Reasoning
1. **Game Engine is Core IP**: The game simulation logic is what makes this project unique. Frontend can be built on any framework later.

2. **Phase 2 is Working Well**: We have a solid game engine with:
   - Complete at-bat flow working
   - Dice system with audit trail
   - State management and persistence
   - 54+ unit tests
   - Integration tests

3. **OAuth is Not Blocking**: We can:
   - Use stub auth for development/testing
   - Add real Discord OAuth later (2-3 days of work)
   - Many games launch without OAuth initially

4. **Frontend Can Wait**:
   - Frontend is 4-6 weeks of work minimum
   - Game logic may still evolve
   - Building UI now might mean rebuilding later
   - Can use scripts/Postman for testing

5. **Current Approach is Working**:
   - Manual test scripts validate functionality
   - pytest integration tests cover critical paths
   - Can run complete games via Python

### Immediate Next Steps (Continue Phase 2/3)

**Week 6 (Phase 2)**: League Features & Integration
- [ ] League configuration system (SBA and PD configs)
- [ ] Complete result charts (beyond simplified)
- [ ] API client for league data
- [ ] Player/card data integration

**Weeks 7-9 (Phase 3)**: Complete Game Features
- [ ] All strategic decisions (steals, bunts, hit-and-run)
- [ ] Substitution system
- [ ] Pitcher fatigue and changes
- [ ] AI opponent implementation

**Weeks 10-11 (Phase 4)**: Polish & Testing
- [ ] Comprehensive test coverage
- [ ] Performance optimization
- [ ] Game state recovery testing
- [ ] Documentation

### When to Revisit Phase 1

**Trigger Points**:
1. **After Phase 3 Complete**: Game mechanics fully implemented and tested
2. **When Ready for User Testing**: Need UI for stakeholders to test
3. **Before Public Launch**: Real auth required for production

**Estimated Effort**:
- Discord OAuth integration: 2-3 days
- Basic frontend (SBA league only): 2-3 weeks
- Full frontend (both leagues): 4-6 weeks
- WebSocket game events: 1 week

## If You Choose to Complete Phase 1

### Phase 1 Completion Tasks

#### 1. Discord OAuth Implementation (3-5 days)
- [ ] Create Discord app in Discord Developer Portal
- [ ] Implement OAuth callback endpoint
- [ ] Add user model to database
- [ ] Store Discord user data
- [ ] Generate and manage sessions
- [ ] Add refresh token logic

#### 2. Frontend - SBA League (2-3 weeks)
- [ ] Initialize Nuxt 3 project (frontend-sba/)
- [ ] Setup Tailwind CSS
- [ ] Create authentication pages (login, callback)
- [ ] Create game lobby (list games, create game)
- [ ] Create game room (player view)
- [ ] WebSocket integration for real-time updates
- [ ] Basic UI components (scoreboard, lineup, decision panel)

#### 3. Frontend - PD League (1-2 weeks after SBA)
- [ ] Clone SBA frontend structure
- [ ] Customize branding/styling for PD
- [ ] Adjust for PD-specific features
- [ ] Test with PD league data

#### 4. WebSocket Game Events (1 week)
- [ ] Implement game state broadcast
- [ ] Add decision submission events
- [ ] Add play resolution events
- [ ] Handle errors and reconnection
- [ ] Test with multiple clients

## Decision Required

**What should we do?**

**Recommended**: Continue with Phase 2/3, defer Phase 1 completion until game engine is solid.

**Alternative**: Complete Phase 1 now if stakeholder demos are critical.

**Hybrid**: Build minimal frontend (just game room, no OAuth) for internal testing.

---

## Notes

- This document captures the gap between planned Phase 1 and actual implementation
- The backend infrastructure we have is **sufficient** for game engine development
- Frontend and OAuth are **nice to have**, not **required** for core development
- We can always come back and complete Phase 1 later

## Updates

- **2025-10-25**: Initial assessment created
- **Next Review**: After Week 6 (Phase 2 complete) or when stakeholder demo is requested