paper-dynasty-gameplay-webapp/.claude/web-migration-v2.md

Paper Dynasty Web App Migration Plan v2.0

Model/Service Architecture Edition

Project Overview

Migrating the baseball gameplay functionality from the Discord app (../discord-app/) to a standalone web application using FastAPI + Model/Service Architecture. This approach provides better separation of concerns, testability, and scalability compared to the original monolithic migration plan.

Architecture Overview

Why Model/Service Architecture?

Based on analysis of the Discord app complexity (15K+ line files), a service-oriented approach will:

• Improve Testability: Services can be unit tested independently
• Enhance Maintainability: Clear separation between business logic and web framework
• Enable Scalability: Easy to add caching, background tasks, API versioning
• Future-Proof: Ready for mobile API, microservices, or different frontends

Technology Stack

• Backend: FastAPI + SQLModel + PostgreSQL
• Architecture: Model/Service/Controller pattern
• Frontend: Jinja2 templates + HTMX + TailwindCSS
• Testing: pytest with comprehensive service unit tests
• Real-time: HTMX polling with WebSocket upgrade path

---

Progress Tracking

🚧 Current Phase

• Phase 1: Service Foundation & Models (Days 1-4)

📋 Upcoming Phases

• Phase 2: Core Game Services (Days 5-9)
• Phase 3: Web Interface with Services (Days 10-14)
• Phase 4: Advanced Features & Optimization (Days 15-17)

---

Phase 1: Service Foundation & Models (Days 1-4)

Day 1: Project Setup & Service Foundation

Tasks

• Initialize FastAPI project with service-oriented structure
• Set up dependency injection patterns for services
• Create base service classes and interfaces
• Configure logging with rotating handlers
• Set up virtual environment and requirements

Service Architecture Setup

app/
├── services/
│   ├── __init__.py
│   ├── base_service.py        # Base service class
│   └── service_container.py   # Dependency injection
├── models/
├── routers/
├── engine/
└── repositories/              # Optional data access layer

Code Review Checklist - Foundation

• Service base classes follow single responsibility principle
• Dependency injection properly configured
• Logging follows rotating pattern from user's CLAUDE.md
• Virtual environment properly configured
• Project structure supports service-oriented development

Success Criteria

• FastAPI server starts without errors
• Base service classes created and testable
• Dependency injection working
• Service unit test framework established

---

Day 2: Database Models Migration

Tasks

• Migrate core gameplay models from ../discord-app/in_game/gameplay_models.py
• Remove Discord dependencies (discord.Embed, etc.)
• Add web-specific models (sessions, preferences, notifications)
• Set up PostgreSQL with Docker for testing
• Create model validation and relationship tests

Models to Migrate

• Game, Team, Player, Lineup, Play (core gameplay)
• Card, Cardset, ManagerAi (game content)
• WebSession, UserPreferences, GameViewState (web-specific)

Code Review Checklist - Models

• All Discord imports removed
• Field types and constraints validated for PostgreSQL
• Relationships properly defined with foreign keys
• Web-specific models added for session management
• Model tests cover creation, relationships, and validation

Success Criteria

• All models work with PostgreSQL
• 90%+ test coverage on model functionality
• Foreign key relationships properly defined
• Web session models support user management

---

Day 3: Core Engine Migration (Stateless)

Tasks

• Migrate ../discord-app/dice.py → engine/dice.py
• Migrate ../discord-app/in_game/simulations.py → engine/simulation.py
• Create engine/calculations.py for statistics and WPA
• Ensure engine components are stateless and pure
• Add comprehensive engine unit tests

Engine Components

• dice.py: Dice rolling, fielding checks, X-chart integration
• simulation.py: Pitcher vs batter mechanics, outcome calculation
• calculations.py: Statistics, WPA, game metrics

Code Review Checklist - Engine

• All engine functions are pure (no side effects)
• Random operations use proper seeding for testing
• No Discord dependencies remain
• Type hints added for all functions
• Edge cases in game rules properly handled

Success Criteria

• Engine components are stateless and testable
• Dice probability distributions validated
• Pitcher vs batter simulation accuracy confirmed
• 95%+ test coverage on core engine logic

---

Day 4: Service Layer Foundation

Tasks

• Create services/game_service.py with basic game management
• Create services/user_service.py for session management
• Create services/auth_service.py for Discord OAuth
• Implement service dependency injection in FastAPI
• Add service unit tests with mocked dependencies

Service Interfaces

class GameService:
    async def create_game(self, away_team_id: int, home_team_id: int) -> Game
    async def get_game(self, game_id: int) -> Game
    async def list_active_games(self) -> List[Game]

class UserService:
    async def create_session(self, discord_user_id: int) -> WebSession
    async def get_user_preferences(self, session_id: str) -> UserPreferences

class AuthService:
    async def authenticate_discord(self, oauth_code: str) -> WebSession
    async def validate_session(self, session_id: str) -> bool

Code Review Checklist - Services

• Services have clear, single responsibilities
• All service methods have type hints
• Services use dependency injection for database sessions
• Service unit tests use mocked dependencies
• Business logic separated from data access

Success Criteria

• Basic services implement core functionality
• Services can be unit tested independently
• Dependency injection working in FastAPI routes
• Service interfaces support expected web app features

---

Phase 2: Core Game Services (Days 5-9)

Day 5: Gameplay Service Architecture

Tasks

• Extract complex gameplay logic from ../discord-app/command_logic/logic_gameplay.py
• Create services/gameplay_service.py for core game flow
• Implement play execution and validation
• Add inning management and state transitions
• Create comprehensive gameplay service tests

GameplayService Responsibilities

• Play execution and validation
• Game state management
• Inning progression logic
• Score calculation and updates
• Game completion detection

---

Day 6: AI Service Implementation

Tasks

• Migrate ../discord-app/in_game/ai_manager.py → services/ai_service.py
• Remove Discord interaction dependencies
• Implement AI decision-making for automated teams
• Add AI personality and difficulty settings
• Create AI behavior validation tests

AIService Responsibilities

• Manager AI decision making
• Lineup optimization
• Pitching decisions
• Defensive positioning
• Strategic game management

---

Day 7: Advanced Game Services

Tasks

• Create services/simulation_service.py for game simulation orchestration
• Implement services/statistics_service.py for player/team stats
• Add services/notification_service.py for real-time updates
• Integrate services with each other using dependency injection
• Add integration tests for service interactions

---

Days 8-9: Service Integration & Testing

Tasks

• Complete end-to-end service integration
• Add performance optimization for service calls
• Implement caching strategies for expensive operations
• Create comprehensive integration test suite
• Validate service architecture with complex game scenarios

Code Review Checklist - Service Integration

• Services interact cleanly without tight coupling
• Database queries optimized (no N+1 issues)
• Error handling propagates correctly through service layers
• Performance acceptable for concurrent users
• All service interactions have integration tests

Success Criteria

• Complete game can be simulated using services
• All services have 90%+ unit test coverage
• Integration tests validate full game flows
• Performance benchmarks met for service calls

---

Phase 3: Web Interface with Services (Days 10-14)

Day 10: FastAPI Route Architecture

Tasks

• Create routers/games.py using GameService
• Create routers/auth.py using AuthService
• Create routers/api.py for HTMX endpoints
• Implement dependency injection for services in routes
• Add route-level error handling and validation

Route Design Pattern

@router.post("/games/start")
async def start_game(
    request: StartGameRequest,
    game_service: GameService = Depends(get_game_service),
    user_service: UserService = Depends(get_user_service)
):
    # Thin controller - delegate to services
    session = await user_service.validate_session(request.session_id)
    game = await game_service.create_game(
        away_team_id=request.away_team_id,
        home_team_id=request.home_team_id
    )
    return {"game_id": game.id}

---

Day 11: Authentication & Session Management

Tasks

• Implement Discord OAuth flow using AuthService
• Create session management with UserService
• Add user preference handling
• Implement authentication middleware
• Add authentication integration tests

---

Day 12-13: Game Interface Implementation

Tasks

• Create game lobby system using GameService
• Implement real-time game board with GameplayService
• Add player action forms with service validation
• Create scoreboard using StatisticsService
• Implement HTMX polling for live updates

---

Day 14: Web Interface Polish

Tasks

• Add comprehensive error handling in routes
• Implement responsive design with TailwindCSS
• Add client-side validation with HTMX
• Create user preference management interface
• Add end-to-end web interface tests

Code Review Checklist - Web Interface

• Routes are thin, delegating business logic to services
• HTMX requests handle errors gracefully
• Forms have proper validation (client and server-side)
• UI is responsive and mobile-friendly
• Game state updates are atomic through services

Success Criteria

• Complete single-player game flow working
• Discord OAuth login/logout functional
• Real-time updates working via HTMX polling
• Responsive design works on mobile and desktop
• All web interfaces use services (no direct database access)

---

Phase 4: Advanced Features & Optimization (Days 15-17)

Day 15: Repository Layer (Optional)

Tasks

• Evaluate need for repository pattern for complex queries
• Implement repositories/game_repository.py if needed
• Add query optimization and caching
• Refactor services to use repositories
• Add repository unit tests

Repository Pattern (If Needed)

class GameRepository:
    def __init__(self, session: Session):
        self.session = session

    async def get_games_with_stats(self, filters: GameFilters) -> List[Game]:
        # Complex query logic separated from service
        pass

class GameService:
    def __init__(self, session: Session, game_repo: GameRepository):
        self.session = session
        self.game_repo = game_repo

    async def get_leaderboard(self, filters: GameFilters) -> List[GameStats]:
        # Service uses repository for complex queries
        games = await self.game_repo.get_games_with_stats(filters)
        return self._calculate_leaderboard(games)

---

Day 16: Performance & Caching

Tasks

• Add Redis caching for expensive service operations
• Implement database query optimization
• Add performance monitoring and metrics
• Optimize service call patterns
• Add load testing for concurrent users

---

Day 17: Final Polish & Documentation

Tasks

• Complete comprehensive test suite (unit, integration, e2e)
• Add API documentation with FastAPI auto-generation
• Performance optimization and final benchmarking
• Code review and refactoring
• Deployment preparation

---

Testing Architecture

Test Structure

tests/
├── unit/                       # Fast, isolated unit tests
│   ├── services/               # Service unit tests (most important)
│   │   ├── test_game_service.py
│   │   ├── test_gameplay_service.py
│   │   ├── test_ai_service.py
│   │   └── test_user_service.py
│   ├── engine/                 # Engine unit tests
│   │   ├── test_dice.py
│   │   ├── test_simulation.py
│   │   └── test_calculations.py
│   └── models/                 # Model validation tests
│       └── test_models.py
├── integration/                # Service + database integration
│   ├── test_game_flow.py
│   ├── test_auth_flow.py
│   └── test_service_integration.py
└── e2e/                       # Full application tests
    ├── test_game_creation.py
    ├── test_gameplay_flow.py
    └── test_user_journey.py

Testing Priorities

Unit Tests (90%+ Coverage Required)

• Critical: All service methods, core engine functions
• Important: Model validation, business logic edge cases
• Nice to have: Repository methods (if implemented)

Integration Tests (80%+ Coverage)

• Critical: Service interactions, database transactions
• Important: Authentication flows, game state persistence
• Nice to have: Performance characteristics

E2E Tests (Happy Path Coverage)

• Critical: Complete game creation and play flow
• Important: User authentication and session management
• Nice to have: Error handling and edge cases

---

Architecture Decisions

Service Layer Benefits

• Testability: Services can be unit tested with mocked dependencies
• Maintainability: Business logic centralized, not scattered across routes
• Scalability: Easy to add caching, background tasks, monitoring
• Flexibility: Services can be used by different interfaces (web, API, CLI)

Repository Pattern (Optional)

• When to use: Complex queries, multiple data sources, query optimization
• When to skip: Simple CRUD operations, small project scope
• Decision: Evaluate during Day 15 based on query complexity

Dependency Injection Strategy

• FastAPI Depends(): For HTTP request-scoped dependencies
• Service constructors: For service-to-service dependencies
• Configuration: Environment-based configuration injection

---

Migration Notes & Decisions

Service Extraction Strategy

1. Identify Business Logic: Extract from Discord command handlers
2. Create Service Interface: Define clear method signatures
3. Write Tests First: Test-driven service development
4. Implement Service: Pure business logic, no framework dependencies
5. Integrate with Routes: Thin controllers using services

Discord App Analysis for Service Extraction

High-Value Extractions

• command_logic/logic_gameplay.py (4,186 lines) → Multiple services
• in_game/ai_manager.py → services/ai_service.py
• Game creation/management → services/game_service.py
• User/session management → services/user_service.py

Keep as Stateless Engine

• dice.py → engine/dice.py (pure functions)
• in_game/simulations.py → engine/simulation.py (calculations)

---

Success Criteria

Architecture Quality

• Clear separation: Models → Services → Controllers (Routes)
• Services have single, well-defined responsibilities
• Business logic not mixed with web framework code
• Dependency injection working throughout application

Code Quality Standards

• Services have 90%+ unit test coverage
• Integration tests cover service interactions
• Type hints on all service methods
• Error handling appropriate for each layer
• Performance acceptable for multiple concurrent users

Migration Success

• Working single-player baseball game with Discord OAuth
• Live scoreboard with HTMX real-time updates
• Clean, service-oriented codebase ready for scaling
• Comprehensive test coverage across all layers
• Responsive web interface (mobile + desktop)
• No Discord-specific dependencies remaining

Service Architecture Validation

• Services can be unit tested independently
• Business logic easily modifiable without touching routes
• New features can be added by extending services
• Multiple interfaces (web, API) can use same services

---

Future Enhancements (Post-MVP)

Microservices Evolution

• Services are designed to be extracted into microservices later
• Clean service interfaces support API versioning
• Database access patterns support service splitting

Advanced Features

• Background task processing using service layer
• Multiple client support (mobile app, desktop)
• Real-time multiplayer using service orchestration
• Analytics and monitoring built into service layer

---

Notes for Future AI Agents

Service-First Development

1. Always start with services when adding new features
2. Write service tests first before implementation
3. Keep routes thin - delegate to services
4. Test services independently with mocked dependencies
5. Use dependency injection for all service interactions

Migration Best Practices

1. Extract business logic from Discord command handlers
2. Remove all Discord dependencies before service implementation
3. Test service logic independently of web framework
4. Integrate services into routes using FastAPI Depends()
5. Validate service architecture with integration tests

Maintenance Guidelines

• Update service tests when changing business logic
• Keep service interfaces stable for backward compatibility
• Add new features by extending services, not routes
• Monitor service performance and add caching as needed
• Document service interactions and dependencies

---

Remember: This migration uses Model/Service Architecture to create a scalable, maintainable web application. Always prioritize clean service design and comprehensive testing over speed of development. The service layer is the foundation that will support future growth and feature additions.