major-domo-v2/commands/transactions/DESIGN.md

Transaction System Design - Discord Bot v2.0

Analysis of Existing System

Based on the analysis of ../discord-app/cogs/transactions.py, here are the key components and expected outcomes:

Core Commands & Expected Outcomes

1. /dropadd (Primary Transaction Command)

Purpose: Handle free agent signings and minor league roster moves Expected Outcomes:

• Create private transaction channel for team
• Guide user through interactive transaction process
• Add/drop players to/from Major League and Minor League rosters
• Validate roster limits and legality
• Schedule transactions for next week execution
• Log all moves for processing during freeze period

User Flow:

1. User runs /dropadd
2. Bot creates private channel with team permissions
3. Interactive Q&A for Minor League adds/drops
4. Interactive Q&A for Major League adds/drops
5. Roster validation and error checking
6. Transaction confirmation and scheduling

2. /ilmove (Injury List Management)

Purpose: Handle injured list moves during active weeks Expected Outcomes:

• Move players to/from injury list immediately (not next week)
• Validate IL move legality
• Update current roster immediately
• Log IL transaction

3. /rule34 (Draft Lottery)

Purpose: 50/50 chance between actual draft board or "rule34" redirect Expected Outcomes:

• 50% chance: Redirect to legitimate draft spreadsheet
• 50% chance: Redirect to rule34 search (league humor)

4. /mymoves (Transaction Status)

Purpose: Show user's pending and scheduled transactions Expected Outcomes:

• Display current week pending moves
• Display next week scheduled moves
• Show frozen/processed moves
• Option to show cancelled moves
• Organized by week and status

5. /legal (Roster Validation)

Purpose: Check roster legality for current and next week Expected Outcomes:

• Validate current week roster
• Validate next week roster (with pending transactions)
• Check roster limits (players, positions, salary, etc.)
• Display violations with clear error messages
• Show WARA totals and roster breakdowns

6. /tomil (Post-Draft Demotions)

Purpose: Move players to minor leagues immediately after draft (Week 0 only) Expected Outcomes:

• Only works during Week 0 (post-draft)
• Immediate player moves to MiL team
• Validate moves are legal
• Punishment mechanism for use outside Week 0 (role removal)

Background Processing

7. Weekly Transaction Processing

Purpose: Automated transaction execution during freeze periods Expected Outcomes:

• Freeze period begins: Monday 12:00 AM (development schedule)
• Process all pending transactions with priority system
• Resolve contested transactions (multiple teams want same player)
• Update rosters for new week
• Send transaction logs to transaction-log channel
• Freeze period ends: Saturday 12:00 AM

8. Transaction Priority System

Expected Outcomes:

• Priority 1: Major League transactions (higher priority)
• Priority 2: Minor League transactions (lower priority)
• Within priority: Worse record gets priority (lower win %)
• Tie-breaker: Random number
• Contested players go to highest priority team

Data Models Needed

Transaction Model

@dataclass
class Transaction:
    id: str
    season: int
    week: int
    team_abbrev: str
    move_type: str  # 'dropadd', 'ilmove', 'tomil'
    moves: List[PlayerMove]
    status: str  # 'pending', 'frozen', 'processed', 'cancelled'
    created_at: datetime
    processed_at: Optional[datetime]

PlayerMove Model

@dataclass  
class PlayerMove:
    player_name: str
    player_id: int
    from_team: str
    to_team: str
    move_type: str  # 'add', 'drop', 'il_to_active', 'active_to_il'

TransactionPriority Model (exists)

@dataclass
class TransactionPriority:
    roster_priority: int  # 1=Major, 2=Minor
    win_percentage: float
    random_tiebreaker: int
    move_id: str
    major_league_team_abbrev: str
    contested_players: List[str]

Services Needed

TransactionService

• CRUD operations for transactions
• Transaction validation logic
• Roster checking and limits
• Player availability checking

RosterService

• Get current/next week rosters
• Validate roster legality
• Calculate roster statistics (WARA, positions, etc.)
• Handle roster updates

TransactionProcessorService

• Weekly freeze period processing
• Priority calculation and resolution
• Contested transaction resolution
• Roster updates and notifications

Modernization Changes

From Old System → New System

1. Commands: @commands.command → @app_commands.command with @logged_command
2. Error Handling: Manual try/catch → Decorator-based standardized handling
3. Interactive Flow: Old Question class → Discord Views with buttons/modals
4. Database: Direct db_calls → Service layer with proper models
5. Logging: Manual logging → Automatic with trace IDs
6. Validation: Inline validation → Service-based validation with proper error types
7. Channel Management: Manual channel creation → Managed transaction sessions
8. User Experience: Text-based Q&A → Rich embeds with interactive components

Pseudo-Code Design

# Main Transaction Commands
class TransactionCommands(commands.Cog):
    
    @app_commands.command(name="dropadd", description="Make roster moves for next week")
    @logged_command("/dropadd")
    async def dropadd(self, interaction: discord.Interaction):
        # 1. Validate user has team and season is active
        # 2. Create transaction session with private thread/channel
        # 3. Launch TransactionFlow view with buttons for different move types
        # 4. Handle interactive transaction building
        # 5. Validate final transaction
        # 6. Save and schedule transaction
        
    @app_commands.command(name="ilmove", description="Make immediate injury list moves")
    @logged_command("/ilmove")  
    async def ilmove(self, interaction: discord.Interaction):
        # 1. Validate current week (not freeze period)
        # 2. Launch ILMoveView for player selection
        # 3. Process move immediately (no scheduling)
        # 4. Update current roster
        
    @app_commands.command(name="mymoves", description="View your pending transactions")
    @logged_command("/mymoves")
    async def mymoves(self, interaction: discord.Interaction):
        # 1. Get user's team
        # 2. Fetch pending/scheduled transactions
        # 3. Create comprehensive embed with transaction status
        
    @app_commands.command(name="legal", description="Check roster legality")
    @logged_command("/legal")
    async def legal(self, interaction: discord.Interaction, team: Optional[str] = None):
        # 1. Get target team (user's team or specified team)
        # 2. Validate current week roster
        # 3. Validate next week roster (with pending transactions)
        # 4. Create detailed legality report embed

# Interactive Views
class TransactionFlowView(discord.ui.View):
    # Modern Discord UI for transaction building
    # Buttons for: Add Player, Drop Player, Minor League, Done
    # Modal dialogs for player input
    # Real-time validation feedback

class ILMoveView(discord.ui.View):
    # Injury list move interface
    # Player selection dropdown
    # Direction buttons (IL → Active, Active → IL)

# Services
class TransactionService(BaseService[Transaction]):
    async def create_transaction(team_id: int, moves: List[PlayerMove]) -> Transaction
    async def validate_transaction(transaction: Transaction) -> ValidationResult
    async def get_pending_transactions(team_id: int) -> List[Transaction]
    
class RosterService:
    async def get_roster(team_id: int, week: str) -> TeamRoster  # 'current' or 'next'
    async def validate_roster_legality(roster: TeamRoster) -> RosterValidation
    async def apply_transaction(roster: TeamRoster, transaction: Transaction) -> TeamRoster

class TransactionProcessor:
    async def process_weekly_transactions() -> ProcessingResult
    async def calculate_priorities(transactions: List[Transaction]) -> List[TransactionPriority] 
    async def resolve_contests(transactions: List[Transaction]) -> ResolutionResult

Implementation Priority

1. Phase 1: Basic commands (/mymoves, /legal) - Read-only functionality
2. Phase 2: Transaction models and services - Data layer
3. Phase 3: Interactive transaction creation (/dropadd, /ilmove) - Core functionality
4. Phase 4: Weekly processing system - Automation
5. Phase 5: Advanced features (/rule34, /tomil) - Nice-to-have

Key Modernization Benefits

• User Experience: Rich Discord UI instead of text-based Q&A
• Error Handling: Comprehensive validation with clear error messages
• Performance: Service layer with proper caching and concurrent operations
• Maintainability: Clean separation of concerns, proper models, standardized patterns
• Reliability: Proper transaction handling, rollback capabilities, audit logging
• Security: Permission validation, input sanitization, rate limiting