cal/strat-gameplay-webapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
751dcaf972
strat-gameplay-webapp/.claude/PHASE_1_CATCHUP_PLAN.md
Cal Corum f9aa653c37 CLAUDE: Reorganize Week 6 documentation and separate player model specifications 
Split player model architecture into dedicated documentation files for clarity
and maintainability. Added Phase 1 status tracking and comprehensive player
model specs covering API models, game models, mappers, and testing strategy.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-25 23:48:57 -05:00

7.3 KiB
Raw Blame History

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