paper-dynasty-discord/.plans/model-service-architecture.md

Model/Service Architecture Implementation Plan

Overview

This document outlines the implementation plan for building a unified model/service architecture across the Paper Dynasty application, with primary focus on the Discord bot component which serves as the local cache for API data during gameplay.

Current State Analysis

PostgreSQL Models (Discord Bot)

• Location: in_game/gameplay_models.py
• Framework: SQLModel-based with ~20+ domain models
• Core Entities: Game, Team, Player, Card, Lineup, Play, ManagerAi
• Features: Complex relationships, proper foreign keys, cascading deletes
• Purpose: Local cache for API data during gameplay sessions

Existing Service Patterns

• API Layer: api_calls.py - HTTP requests to FastAPI backend
• Data Cache: in_game/data_cache.py - Dataclass wrappers for API responses
• Query Layer: in_game/gameplay_queries.py - SQLModel query functions
• Legacy DB: db_calls_gameplay.py - Peewee-based patterns (to be deprecated)

Current Data Flow

FastAPI Database → HTTP API → Local PostgreSQL Cache → Game Logic

Proposed Architecture

Directory Structure

models/              # Domain models (refactored from gameplay_models.py)
├── base.py         # Base model classes and mixins
├── game.py         # Game-related models
├── player.py       # Player/Card models  
├── team.py         # Team models
└── stats.py        # Statistics models

services/           # Business logic layer
├── base.py         # Base service class with common patterns
├── game_service.py # Game management operations
├── team_service.py # Team operations
├── card_service.py # Card/Player operations
└── cache_service.py # Data synchronization with API

repositories/       # Data access layer
├── base.py         # Base repository with CRUD operations
├── game_repo.py    # Game-specific queries
├── team_repo.py    # Team-specific queries
└── player_repo.py  # Player/Card queries

Implementation Phases

Phase 1: Service Layer Foundation (Weeks 1-2)

Objectives:

• Create base service/repository classes
• Extract existing gameplay_queries.py into proper service modules
• Establish consistent patterns for dependency injection

Tasks:

1. Create services/base.py with common service patterns
2. Create repositories/base.py with CRUD operations
3. Extract game operations from gameplay_queries.py → services/game_service.py
4. Extract team operations → services/team_service.py
5. Extract player/card operations → services/card_service.py
6. Create comprehensive unit tests for new service layer

Files to Create:

• services/__init__.py
• services/base.py
• services/game_service.py
• services/team_service.py
• services/card_service.py
• repositories/__init__.py
• repositories/base.py
• repositories/game_repo.py
• repositories/team_repo.py
• repositories/player_repo.py

Success Criteria:

• All existing queries moved to appropriate services
• Service classes follow consistent patterns
• 100% test coverage for new service layer
• No breaking changes to existing cog functionality

Phase 2: Model Refactoring (Weeks 3-4)

Objectives:

• Refactor existing models with base classes
• Add proper validation and optimize relationships
• Implement model mixins for shared behavior

Tasks:

1. Create models/base.py with base model classes
2. Split gameplay_models.py into logical modules:
   • models/game.py - Game, Play, GameCardsetLink
   • models/team.py - Team, Lineup, RosterLink
   • models/player.py - Player, Card, PositionRating
   • models/stats.py - BattingCard, PitchingCard, Scouting models
3. Add base mixins for common fields (timestamps, soft deletes)
4. Optimize database indexes and constraints
5. Update all imports across the codebase
6. Run full test suite to ensure no regressions

Files to Modify:

• in_game/gameplay_models.py → Split into models/ directory
• All files importing from gameplay_models.py
• Database migration files

Success Criteria:

• Models follow consistent inheritance patterns
• All relationships properly defined with optimized queries
• Database performance maintained or improved
• Zero test failures after refactoring

Phase 3: Service Integration (Weeks 5-6)

Objectives:

• Replace direct SQLModel queries in cogs with service calls
• Implement proper transaction management and error handling
• Add caching strategies at service level

Tasks:

1. Refactor cogs/gameplay.py to use service layer
2. Refactor cogs/players/ modules to use services
3. Refactor command_logic/logic_gameplay.py
4. Implement service dependency injection in cogs
5. Add comprehensive error handling with proper exception types
6. Implement service-level caching for frequently accessed data
7. Add logging and monitoring to service operations

Files to Modify:

• cogs/gameplay.py
• cogs/players/*.py
• command_logic/logic_gameplay.py
• in_game/ai_manager.py
• in_game/game_helpers.py

Success Criteria:

• No direct database access in cogs (all through services)
• Proper error handling and transaction management
• Improved performance through service-level caching
• All existing functionality preserved

Phase 4: API Synchronization & Optimization (Weeks 7-8)

Objectives:

• Build unified data sync service for API ↔ PostgreSQL cache
• Implement background sync tasks and health checks
• Add performance monitoring and optimization

Tasks:

1. Create services/cache_service.py for API synchronization
2. Implement background tasks for data freshness
3. Add conflict resolution for concurrent modifications
4. Create health check endpoints for data consistency
5. Implement performance monitoring and alerting
6. Add database connection pooling optimization
7. Create data migration utilities for schema changes

Files to Create:

• services/cache_service.py
• services/sync_service.py
• monitoring/health_checks.py
• monitoring/performance_metrics.py

Success Criteria:

• Automatic data synchronization with API
• Health monitoring and alerting in place
• Performance metrics collection
• Zero data consistency issues

Migration Strategy

Backwards Compatibility

• All changes will maintain backwards compatibility during transition
• Original gameplay_models.py will remain until Phase 2 completion
• Gradual migration with feature flags for rollback capability

Testing Strategy

• Comprehensive unit tests for all new service classes
• Integration tests for service layer interactions
• Performance tests to ensure no regressions
• Load tests for cache synchronization under heavy gameplay

Rollback Plan

• Each phase can be independently rolled back
• Feature flags allow selective activation of new architecture
• Database migrations are reversible
• Monitoring alerts for performance degradation

Benefits

Separation of Concerns

• Clear boundaries between models, business logic, and data access
• Easier to reason about and maintain code
• Reduced coupling between components

Testability

• Service layer can be easily mocked and tested
• Better unit test coverage and reliability
• Faster test execution with mocked dependencies

Maintainability

• Centralized business logic and consistent patterns
• Easier onboarding for new developers
• Reduced code duplication

Performance

• Optimized queries and caching strategies
• Better database connection management
• Reduced API calls through intelligent caching

Scalability

• Easy to extend with new features and models
• Prepared for microservice architecture if needed
• Better resource utilization

Timeline

• Total Duration: 8 weeks
• Phase 1: Weeks 1-2 (Foundation)
• Phase 2: Weeks 3-4 (Model Refactoring)
• Phase 3: Weeks 5-6 (Service Integration)
• Phase 4: Weeks 7-8 (Optimization)

Risk Mitigation

Technical Risks

• Database Performance: Continuous monitoring during migration
• Data Consistency: Comprehensive testing and validation
• Breaking Changes: Gradual migration with backwards compatibility

Timeline Risks

• Scope Creep: Clear phase boundaries and success criteria
• Testing Overhead: Automated testing pipeline
• Integration Issues: Early integration testing and validation

Success Metrics

• Zero downtime during migration
• Performance maintained or improved (< 5% regression acceptable)
• 100% test coverage for new architecture
• Reduced average development time for new features by 30%
• Improved code maintainability score (SonarQube metrics)

---

This plan serves as the foundation for modernizing the Paper Dynasty architecture while maintaining stability and performance during the transition.