⚽🔥🦈 KickPick.App

🏟️ Multi-Team Management

• Multiple Independent Teams: Create and manage any number of teams in one app
• Team Format Support: 4v4, 7v7, 9v9, and 11v11 team formats with appropriate UI for each
• Team Switcher: Dropdown selector to switch between teams instantly
• Create New Team: Name, format (4/7/9/11 players per side), and default formation
• Edit Team: Rename team and manage the full player roster dynamically
• Dynamic Player Roster: Add or remove players from a team at any time
• Team-Scoped Data: Templates, games, ratings, and priority players are stored independently per team
• Switch Confirmation: Warns before switching teams if unsaved changes exist
• LocalStorage Migration: Automatically migrates data from legacy single-team storage format

🔒 Password Protection

• Session-Based Access Control: Password prompt displayed on first load of each browser session
• Shake Animation: Visual feedback on incorrect password entry
• Enter Key Support: Submit password by pressing Enter or clicking the button
• Session Persistence: Authentication state stored in localStorage under a session key
• Transparent Overlay: App content is hidden behind the password overlay until authenticated

⚽ Formation Management

• Customizable Formations: Any valid player combination (goalkeeper + field players)
• Flexible Position Configuration: Dropdown selectors for Fullbacks (0-4), Midfielders (0-4), Forwards (0-4)
• Real-time Validation: Formation must equal exactly the team size
• Dynamic Position Display: Shows current formation (e.g., "1-2-2-2")
• Formation Change Protection: Warns before clearing rotation when changing formations
• Formation Comparison Tool: Test all valid formations (19 for 7v7) across multiple optimization attempts
• Visible Progress Tracking: Real-time display showing current formation being tested and overall progress
• Best Formation Recommendation: Automatically identifies optimal formation with highest total score
• Balance Indicators: Visual badges (Excellent / Good / Fair) for each formation's balance quality
• Quick Formation Selection: Click any formation in comparison results to instantly apply it with its best rotation
• 4v4 Adaptation: Formation controls and comparison button hidden for 4v4 teams (all players always play)

👥 Player Management

• Attendance Tracking: Click-to-toggle attendance for each player
• Visual Absent Status: Grayed out with strikethrough for absent players
• Position Restoration: Absent players return to their original positions when marked present
• Playing Time Display: Shows quarters played (X/4) on every player button
• Dynamic Roster: Add and remove players from the roster via Edit Team modal
• Customizable Priority Players: Full control over which players get 3+ quarters via settings modal
• Position-Specific Ratings: Rate each player 0-3 across multiple position dimensions
• Settings Persistence: Priority players and ratings saved to team-specific localStorage

⚙️ Player Settings System

• Settings Modal: Tabbed interface for Priority Players and Position Ratings configuration
• Priority Players Tab: Grid layout with checkboxes to select which players get preferential playing time (3+ quarters)
• Position Ratings Tab: Table with rating inputs (0-3 scale) for each player across all positions
• 7v7/11v11 Position Rating Columns:
  • Goalkeeper (0-3)
  • Fullback Defense (0-3)
  • Fullback Offense (0-3)
  • Midfield Defense (0-3)
  • Midfield Offense (0-3)
  • Forward Defense (0-3)
  • Forward Offense (0-3)
• 4v4 Position Rating: Single "Strength" rating (0-3) per player for simplified format
• Rating Scale System:
  • 0 = Can't/shouldn't play this position
  • 1 = Below average/backup capability
  • 2 = Average/competent performance
  • 3 = Elite/star player at this position
• Automatic Saving: Settings immediately saved to team-specific localStorage
• Settings Reset: One-click restoration to default priority players and ratings
• Sticky Table Headers: Position ratings table header stays visible while scrolling

📚 Past Games History

• Complete Game Archive: Save finished games with opponent, date, score, and complete rotation details
• Game Metadata Storage: Captures formation, player count, total scores, defensive/offensive breakdown
• Game Notes: Add custom notes to each game (e.g., "Great teamwork in Q2")
• Visual Result Cards: Color-coded game cards with green borders for wins, red for losses, orange for ties
• Result Emoji: 🏆 for wins, 😞 for losses, 🤝 for ties displayed on each card
• Chronological Organization: All games sorted by date with newest first
• Detailed Game View: Click any game to see complete rotation, playing time, positions, and scores
• Quarter-by-Quarter Breakdown: Full position assignments shown for all quarters in detail view
• Playing Time Archive: Historical record of which players played which quarters
• Defense/Offense Percentage Display: Shows scores as percentage of maximum possible in game detail view
• Delete Old Games: Remove unwanted games from history with confirmation
• Team-Scoped Persistence: Games saved separately per team in localStorage
• Season Review Capability: Review entire season's worth of games and rotations

🎯 Optimization Strategy

• ⚖️ Balanced: Equal strength across all quarters - minimizes variance between quarters using standard deviation scoring

🔄 Rotation Generation

• Full Rotation Generation: Generates complete 4-quarter rotation in one click
• 100 Attempt Optimization: Creates 100 different rotations, automatically selects the best
• Formation Comparison Mode: Tests all valid formations (19 for 7v7) with multiple attempts each
• Loading Progress Indicator: Real-time progress display during generation with animated progress bar
• Smart Player Assignment: Respects all rules, constraints, and player ratings automatically

📋 Rotation Rules & Constraints

All rules are enforced automatically by the AI optimization:

• Minimum Playing Time: Every player gets 2 quarters minimum (absolute hard rule)
• Priority Player Distribution: Priority players get 3+ quarters (customizable via settings)
• 75% Priority Rule: 75% of field players are priority players each quarter
• Position Group Minimums: At least 1 priority player at fullback and midfield per quarter
• Goalie Rotation: Each goalie plays maximum once per game (if 4+ goalies available)
• Side Consistency: Players tend to stay on same side (left/center/right) across quarters
• Consecutive Quarter Penalty: Avoids 3+ consecutive quarters for any player
• Position Rating Consideration: AI uses custom player ratings to assign positions optimally
• Eligibility Enforcement: Players only assigned to positions where their rating is > 0

📊 Scoring System

Position Rating System (0-3 Scale):

Score Calculation:

Note: Goalkeeper does not contribute to defense or offense scores. Position ratings guide AI placement priority.

🎨 Manual Rotation Adjustments

• Click-to-Edit Positions: Click any position slot to assign/swap players
• Smart Player Swapping: Swap players between any positions on the field
• Bench Player Assignment: Click bench players to assign to empty positions
• Position Override: Place any player in any position (with warning for non-typical positions)
• Remove Players: Option to clear individual position slots
• Score Impact Preview: See defensive/offensive score changes before confirming substitutions
• Grouped Position Selection: Players organized by Goalkeeper, Fullbacks, Midfielders, Forwards in modal
• Quick Quarter Swap from Stats: Click orange players (4/4) in Playing Time Summary to swap quarters with under-played players
• Position-Aware Swapping: Swap modal shows position, quarter, and score impact for each option
• Priority-Based Swap Options: Red players (1/4) shown first as priority, then yellow players (2/4)

📈 Analytics & Statistics

• Quarter-by-Quarter Scores: Defense/Offense scores for each quarter with max values (e.g., "DEF: 6/8")
• Total Match Scores: Cumulative defense and offense across all quarters
• Playing Time Summary: Grid showing each player's quarters played (X/4)
• Smart Color Coding: Orange for max players (4/4), Yellow for below average, Red for critical (1/4), Blue for balanced
• Interactive Orange Players: Clickable orange badges open quarter swap modal
• Score Breakdown: Detailed quarter-by-quarter breakdown in Total Match Scores section
• Real-time Updates: All statistics update instantly when changes are made
• Formation Comparison Analytics: Compare total score, defense, offense and balance across all valid formations per team format
• Historical Game Statistics: Review past game scores and playing time from completed games archive
• Game Detail View: Defense/Offense shown as percentage of maximum possible

💾 Template System

• Save Templates: Save complete rotations with custom names
• Template Metadata: Automatically tracks formation, optimization mode, player count, total scores, date/time
• Load Templates: Browse and load previously saved rotations
• Template Library: View all saved templates with full details in card format
• Overwrite Protection: Warns before overwriting existing templates with same name
• Delete Templates: Remove unwanted templates from library
• Team-Scoped Persistence: Templates saved per team in localStorage

🔗 Sharing & Export

• Share via URL: Generate shareable link with complete rotation state encoded
• URL State Encoding: Base64-encoded rotation data in URL hash (preserves all settings)
• TinyURL Integration: Create shortened URLs for easy text message sharing
• Copy to Clipboard: One-click copy of share links with confirmation
• Fallback Copy Method: Compatible with older browsers that don't support Clipboard API
• Print/PDF Export: Print-optimized layout with hidden controls (browser Print to PDF)
• Team Mode Detection: Shared URL includes team format so recipients see the correct UI

🎨 User Interface

• Responsive Design: Fully optimized for mobile, tablet, and desktop screens
• Color-Coded Positions: Visual distinction between Goalkeepers (🥅), Fullbacks (🛡️), Midfielders (⚙️), Forwards (⚡)
• Gradient Backgrounds: Professional purple gradient theme throughout
• Hover Effects: Interactive feedback on all clickable elements
• Modal Dialogs: Clean, centered modal interfaces for all actions
• Loading Animations: Spinner with real-time progress counter and animated progress bars
• Toast Notifications: Success/error messages for user actions
• Help Tooltip: Comprehensive feature list accessible via "?" icon in header
• Smooth Transitions: Animated hover states and button interactions
• Tabbed Settings Interface: Organized settings modal with tab navigation
• More Options Toggle: Collapsible advanced options section to keep UI clean

🔍 Visual Indicators

• Playing Time Color System:
  • 🔴 Red (1/4) - Critical, needs immediate attention
  • 🟡 Yellow (below average) - Needs more time
  • 🟠 Orange (max quarters) - Playing most, clickable for swapping
  • 💙 Blue (balanced) - Normal range, no action needed
• Bench Player Color Coding: Same color system applied to bench players for instant visual priority
• Position Fill Status: Gradient fill for assigned positions, dashed border for empty slots
• Bench Display: Clearly separated bench section with player count badge and color-coded playing time
• Score Badges: Color-coded defensive (blue) and offensive (red) score badges per quarter
• Quarter Headers: Large, bold quarter numbers with regenerate buttons
• Absence Indicators: Strikethrough text and red color for absent players
• Hover Tooltips: Orange players show "Click to swap quarters" tooltip on hover
• Result Badges: Win/Loss/Tie indicators on past game cards (green/red/orange)
• Formation Balance Badges: Excellent/Good/Fair indicators in formation comparison results
• Recommendation Badge: Highlights the best formation in comparison results

⚙️ Advanced Features

• Undo Support: Absent players can be restored with their original positions intact
• State Persistence: Current rotation preserved when loading from URL
• Optimization Mode Persistence: Saves selected optimization strategy
• Real-time Updates: All displays update immediately after any change
• Print Mode: Automatically hides controls and optimizes layout for printing
• Browser Compatibility: Works in all modern browsers (Chrome, Firefox, Safari, Edge)
• Position Eligibility Checking: Warns when swapping players to non-typical positions
• Team-Scoped Multi-Storage System: Separate localStorage keys for templates, games, settings, and team data per team
• Legacy Data Migration: Automatically migrates data from older single-team storage format

📱 Mobile Optimizations

• Touch-Friendly Buttons: Large tap targets optimized for fingers
• Responsive Grid Layouts: Automatically adapts to screen size
• Stacked Formation Controls: Vertical layout on small screens
• Full-Width Buttons: Easier tapping on mobile devices
• Optimized Modals: Mobile-friendly player/position selection dialogs
• Scrollable Tables: Position ratings table optimized for mobile viewing
• Compact Past Games Cards: Game history cards stack vertically on mobile

🎯 Smart Algorithm Features

• Multi-Constraint Satisfaction: Balances all rules simultaneously
• Variance Minimization: Reduces score differences between quarters (in Balanced mode)
• Standard Deviation Tracking: Measures rotation balance mathematically
• Consecutive Quarter Detection: Identifies and penalizes 3+ consecutive plays
• Priority-Based Sorting: Smart player selection based on multiple weighted factors
• Target Distribution: Calculates optimal quarter distribution per player type
• Cross-Game Tiebreaker: When non-priority players are tied on current-game quarters, their average quarters per game attended across all past saved games is used to prioritize players who have played less — absences are excluded so a missed game does not unfairly boost a player's priority
• Position Rating Integration: Uses position-specific ratings to guide optimal placement
• Formation-Wide Optimization: Tests all valid formations per team format to find statistically best option