CLAUDE.md

Football Play/Roster Manager - App Documentation

Overview

The Football Play/Roster Manager is a comprehensive React-based web application built for elite football coaches to manage entire offensive systems. This is not just a playbook - it's a complete digital football management system that integrates personnel, formations, concepts, and game planning into one cohesive platform. The app uses TypeScript, Vite, Tailwind CSS, and Zustand for state management with full persistence.

Core Purpose

This app serves as the digital foundation for modern football programs by:

1. Managing Complete Personnel Systems: Track all personnel groups with depth charts and adjusting players
2. Building Modular Play Calls: Combine personnel, formations, concepts, and hash positions into complete play calls
3. Generating Practice Scripts: Create thoughtful, randomized practice scripts within coach-defined constraints
4. Organizing Game Plans: Manage concepts by installation status and usage frequency
5. Tracking Player Assignments: Maintain depth charts for every position in every personnel group
6. Exporting Game-Ready Materials: Generate call sheets and practice scripts in coach-preferred formats

Tech Stack

• Frontend: React 19.1.0 with TypeScript
• Build Tool: Vite 4.5.14
• Styling: Tailwind CSS 3.3.0
• State Management: Zustand 5.0.6 with persistence
• Icons: Lucide React 0.532.0
• Immutable Updates: Immer 10.1.1

System Architecture

Core Philosophy: Modular Football Systems

The app is built around the principle that modern football operates on modular, independent components that combine for infinite possibilities:

• Personnel (who's on the field) × Formation (where they align) × Concepts (what they do) × Hash (field position) = Complete Play System

Each component stands alone but integrates seamlessly, providing maximum flexibility while maintaining systematic teaching principles.

Key Components

1. Personnel Manager with Big Board (PersonnelManagerWithBigBoard.tsx)

Purpose: Revolutionary integrated personnel management combining Big Board roster management with personnel depth charts in an intuitive east-west layout

Core Features:

Big Board System (Left Panel - 1/3 width):

• Master Offensive Roster: Central repository for all offensive players
• Position-Based Organization: Players organized by position (Q, B, A, F, Y, H, X, Z, T, W)
• Complete Player Profiles: Name, jersey number, year in school, height, weight, notes
• Advanced Drag & Drop:
  • Within Position Reordering: Drag players up/down within same position group
  • Cross-Position Movement: Move players between position groups seamlessly
  • Visual Feedback: Opacity changes, drop indicators, hover effects
• Compact Design: 2-column grid, scrollable container, optimized for space
• Inline Editing: Click to edit player details directly in the Big Board

Personnel Groups System (Right Panel - 2/3 width):

• 18 Personnel Groups: 9 base groups + 9 "2" versions for expanded player options
  • ACE (21), JACK (20), QUEEN (11), KING (22), JOKER (20), QUAD (10), FLUSH (00), COWBOY (01), JUMBO (23)
  • All duplicated as "2 ACE", "2 JACK", etc. for additional player depth
• Position Management: Define which positions exist in each personnel group
  • Edit interface with checkbox grid for all 15 positions
  • Smart defaults based on personnel code
  • Prevents invalid player assignments in play generation
• Adjusting Player System: Each personnel group defines which players are the "adjusters"
• Replacement Rules: Automatic position substitutions (e.g., T replaces X in KING personnel)
• Default Formations: Each personnel group has a default formation that auto-populates
• Unlimited Depth Charts: Track 1st, 2nd, 3rd, 4th+ string players for every position in every personnel group
• Personnel Group Management: Create, edit, delete personnel groups (reset function disabled for safety)

Integrated Drag & Drop System:

• Big Board → Depth Charts: Copy players from Big Board to any personnel group depth chart
• Within Depth Charts: Reorder players within position depth charts
• Cross-Position Flexibility: Move players between positions in Big Board
• Visual Drop Indicators: Blue animated lines show exactly where players will be placed
• Bold Player Names: Enhanced readability in depth charts with bold text formatting

East-West Layout Benefits:

• Simultaneous Visibility: See both Big Board and Personnel Groups at the same time
• Independent Scrolling: Each panel scrolls separately for maximum accessibility
• Optimal Screen Usage: Takes advantage of widescreen monitors
• Smooth Dragging: No page constraints - drag freely between sections
• Compact Interface: Smaller buttons and spacing maximize content area

Key Personnel Groups:

ACE (21): 2 RB, 1 TE - Adjusting: A - Default: Right Far
JACK (20): 2 RB, 0 TE - Adjusting: A - Default: Rip Far  
QUEEN (11): 1 RB, 1 TE - Adjusting: F - Default: Rip Dot
KING (22): 2 RB, 2 TE - Adjusting: F,A,T - T replaces X - Default: Right Far
JOKER (20): 2 RB, 0 TE - Adjusting: F - Default: Rip Wing
QUAD (10): 1 RB, 0 TE - Adjusting: H - Default: Right Quad
FLUSH (00): 0 RB, 0 TE - Adjusting: A,H - A replaces B - Default: Rip Empty
COWBOY (01): 0 RB, 1 TE - Adjusting: F,H - F replaces B - Default: Rip Deuce False
JUMBO (23): 2 RB, 3 TE - Adjusting: B,A,T,W - No X or Z - Default: Right Near

2. Play Builder (PlayBuilder.tsx)

Purpose: Central hub for creating complete play calls using modular components

Play Call Structure: [Personnel] [Hash] [Strength] [Formation] [Modification] [Shift] [Motion] [Left Ind Assign] [Left Tag] [Primary Tag] [B Assignment] [Right Ind Assign] [Right Tag]

Key Features:

• 6-Step Play Building Process:

  1. Personnel Selection: Choose from all personnel groups with auto-suggested formations
  2. Hash Position: Select from L/LM/M/RM/R (5-hash system)
  3. Formation: Strength + Type + Modification with flip functionality
  4. Shifts & Motions: Pre-snap adjustments
  5. Left/Right Tags: Multi-person concepts with individual assignments
  6. Primary Tag: Required run/protection concept

• Formation Flip Feature: One-click formation flipping that preserves play call order

  • Flips: Right ↔ Left, Rip ↔ Liz
  • Handles slot calls: Slot Right ↔ Slot Left
  • Maintains X (always left) and Z (always right) positioning rules

• Hash Integration: Full 5-hash system (L/LM/M/RM/R) for field positioning

• Custom Formation Options: Add new strengths, types, and modifications on-the-fly

• Play Call Preview: Live preview of complete play call as you build

Formation Types Available:

• Base: Deuce, Trips, Empty, Ace, Trey, Quad
• Alignment: Dot, Wing, Wait, Trot, Set, True, False, Far, Near
• Custom: Unlimited custom formations via "Add New" functionality

3. Concept Library (ConceptLibrary.tsx)

Purpose: Manage all offensive concepts with installation tracking

Key Features:

• 4 Concept Types: Pass, Run, Blocking, Protection
• Installation Status: Mark concepts as "Installed" vs "Not Installed"
• Tag Box Assignment: Assign concepts to left, right, or primary positions
• Multi-Person vs Individual: Define concept scope and player requirements
• Installation Tracking: Visual indicators and filtering by installation status

Critical Rule: Only "installed" concepts appear in practice script generation when filtered

4. Formation Manager (Currently Removed)

Status: No visual formation builder is currently implemented in the system.

Note: The formation visual builder has been temporarily removed while considering the best systematic approach for implementing Y-strength and formation location protocols. The Play Builder continues to work with text-based formation selection using standard football terminology.

Future Consideration: A systematic formation builder may be re-implemented later that enforces:

• Y-strength positioning rules (Y sets formation strength)
• Formation location protocols (adjusting player positions)
• Visual drag-and-drop with systematic constraints

5. Practice Scripts (PracticeScripts.tsx)

Purpose: Generate intelligent practice scripts with coach-controlled constraints

Key Features:

• Concept-Driven Generation: Select specific concepts to focus practice
• Installation Filtering: Include only plays with installed concepts
• Play Repetition Control: Allow/prevent same play appearing multiple times
• Script Metadata: Name, date, situation, period tracking
• Export Functionality: Download as formatted text files for call sheets
• Play Display: Shows complete play calls with personnel names integrated

6. Practice Plans (PracticePlans.tsx)

Purpose: Revolutionary multi-period practice plan system that transforms single-period script generation into comprehensive practice management

Core Philosophy: "Evolve from single period generator to the ability to generate 1 or more periods or a full practice" - enabling coaches to plan complete practice sessions with multiple focused periods.

Key Components:

• Practice Plan Builder (PracticePlanBuilder.tsx): 4-step wizard for creating complete practice plans
• Period Generator (PeriodGenerator.tsx): Advanced play generation for individual periods with sophisticated filtering
• Practice Timeline (PracticeTimeline.tsx): Visual timeline with drag-and-drop period management
• Export System (practicePlanExport.ts): Multi-format export (CSV, JSON, Text, Period Cards)

Revolutionary Features:

1. Multi-Period Management:

   • Create unlimited practice periods with different types (Individual, 7on7, Team, Red Zone, etc.)
   • Each period has independent settings for play generation
   • Visual timeline shows proportional duration and completion status
   • Drag-and-drop reordering with real-time analytics

2. Sophisticated Period Generation:

   • Granular Filtering: Personnel restrictions, concept focus, metadata filters, installation status
   • Hash Distribution: 6 distribution patterns (Balanced, Field Heavy, Boundary, etc.)
   • Concept Distribution Targets: Set percentage targets for specific concepts
   • Smart Repetition Control: Allow/prevent play repetition with pool management
   • Advanced Settings: Required/forbidden concepts, max plays per concept

3. Practice Templates System:

   • 6 Pre-built Templates: Tuesday Install, Thursday Gameweek, Competition Period, etc.
   • Template Categories: Install, Gameweek, Competition, Custom
   • Smart Defaults: Each template includes period types, durations, and default settings
   • Customizable: Start from template or build from scratch

4. Visual Practice Management:

   • Timeline View: Proportional duration bars with completion indicators
   • Period Cards: Detailed view with settings, play counts, and notes
   • Progress Tracking: Visual indicators for generated vs. target plays
   • Hover Tooltips: Quick access to period details and statistics

5. Comprehensive Export System:

   • Master Script (CSV): Complete practice with all periods, play numbers, hash positions
   • Period Cards (CSV): Individual CSV files for each period
   • Simple Text: Clean text format for coaching staff
   • JSON Backup: Complete practice plan data for sharing/backup

6. Analytics Integration:

   • Real-time Analytics: Concept frequency, personnel distribution, hash patterns
   • Practice Metrics: Total plays, duration, completion percentage
   • Automatic Reporting: Generated analytics with every practice plan

Data Structure:

interface PracticePlan {
  id: string
  name: string
  date: Date
  type: 'full' | 'partial' | 'walkthrough' | 'gameweek' | 'install' | 'competition' | 'custom'
  periods: PracticePeriod[]
  totalPlays: number
  estimatedDuration: number
  analytics?: PracticeAnalytics
  templateId?: string
}

interface PracticePeriod {
  id: string
  name: string
  type: PeriodType
  duration: number
  playCount: number
  plays: PlayCall[]
  settings: PeriodSettings
  order: number
}

Period Types Available:

• Individual: Individual skill work
• Inside Run: Inside running game focus
• Perimeter Run: Outside/perimeter running
• Pass Skeleton (7on7): 7-on-7 passing work
• Team Run: Full team running periods
• Team Pass: Full team passing periods
• Team: Full team scrimmage
• Red Zone: Goal line/red zone specific
• 3rd Down: Third down situations
• 2 Minute: Two-minute drill periods
• Special Situations: Custom situational work

Advanced Filtering Capabilities:

• Installation Status: All/Installed Only/Not Installed concepts
• Personnel Selection: Choose specific personnel groups
• Concept Types: Pass, Run, Protection, Blocking filters
• Metadata Filtering: Filter by custom metadata fields and values
• Hash Preferences: 6 different hash distribution patterns
• Concept Distribution: Set percentage targets for specific concepts

User Workflow:

1. Template Selection: Choose from 6 pre-built templates or start from scratch
2. Practice Details: Set name, date, type, and notes
3. Period Management: Add, edit, reorder periods with visual timeline
4. Play Generation: Use sophisticated filtering to generate plays for each period
5. Review & Export: Review complete practice plan and export in preferred format

Integration Points:

• Play Library: Pulls from complete play library with all filtering options
• Concept Library: Respects installation status and metadata
• Personnel Manager: Uses personnel groups and position availability
• Export Compatibility: Integrates with existing export systems

7. Play Generator (PlayGenerator.tsx & PlayGeneratorSimple.tsx)

Purpose: Revolutionary automated play generation system that transforms coaches from manual play builders into strategic coordinators

Core Philosophy: "If I select just one checkbox, give me just that component. If I select three, give me those three. The system should fill the proper 'column' in the play call structure."

Key Features:

• Granular Component Control: 16 individual checkboxes for complete customization
  • Formation Components: Personnel, Hash, Formation Strength, Formation Type, Formation Modifications (1 & 2)
  • Movement Components: Shift, Motion
  • Concept Components: Left/Right Individual Assignments, Left/Right Tags, Primary Tag (Run), Primary Tag (Protection), B Assignment
• 100% Reliable Generation: If checkbox is checked, component ALWAYS generates (no probability failures)
• Optional Primary Tag: Can generate formation-only or pass-only plays without requiring a primary concept
• Smart Data Filtering:
  • Installation Status: All / Installed Only / Not Installed
  • Concept Type Filters: Pass, Run, Protection, Blocking, Constraints, Crossers, Backfield Action
  • Specific Concept Selection: Scrollable list to choose exact concepts
  • Personnel Group Selection: Choose which personnel groups to use
• Dual Implementation:
  • Embedded in Play Builder for quick generation during play creation
  • Standalone page (Play Generator menu item) for dedicated generation sessions

Revolutionary Play Type Control:

• Primary Tag (Run): Generates only run concepts (POWER, ISO, ZIPPER, etc.)
• Primary Tag (Protection): Generates only protection schemes (SCAT LEFT, BLONDE, etc.)
• Both Selected: Randomly chooses between run and protection
• Neither Selected: No primary tag generated (pure pass plays)

Advanced Features:

• Visual Feedback: Shows available concepts, filtered counts, and selected data in real-time
• Complete Integration: Maintains IMMUTABLE play call order structure
• Coaching Intelligence: Empty selections mean "use all that match other filters"
• Debug Information: Development mode shows concept availability by type and side
• Export Integration: Generated plays integrate seamlessly with Play Library and Practice Scripts

8. Roster Manager (RosterManager.tsx & GroupBuilder.tsx)

Purpose: Comprehensive player roster management and dynamic group creation system for practice organization, team activities, and player logistics

Core Philosophy: Transform roster management from spreadsheets into a powerful organizational tool that handles everything from practice groups to travel arrangements.

Key Features:

Player Management:

• Complete Player Profiles:
  • Basic: Name, jersey number, position, grade level
  • Physical: Height, weight measurements
  • Contact: Phone, email, parent contact information
  • Academic: GPA tracking for study groups
  • Custom tags: Captain, injured, scout team, etc.
• Dynamic Custom Options:
  • Add/delete custom positions (beyond standard QB, RB, etc.)
  • Custom grade levels (FR, SO, JR, SR, or 8th, 9th, etc.)
  • Unlimited custom tags for categorization
  • Custom sides beyond offense/defense
• Bulk Operations:
  • CSV import/export for entire rosters
  • Multi-select for group assignments
  • Bulk delete with confirmation

Advanced Group Generation:

• Granular Control:
  • Specify exact number of groups (2-20)
  • Set fixed group size or auto-distribute
  • Balance by: Random, Alphabetical, Position, Grade, or Side
• Equal Distribution Option:
  • Ensures each group gets equal representation
  • Position balance: Equal QBs, RBs, etc. per group
  • Grade balance: Equal class distribution
  • Side balance: Equal offense/defense split
• Quick Group Actions:
  • One-click grouping by position
  • One-click grouping by grade
  • One-click grouping by side
  • Delete all groups with single button

Template System:

• 8 Default Templates (all editable/deletable):
  • Practice Stations (6-8 rotation groups)
  • Study Groups (academic-based)
  • Conditioning Groups (strength/speed)
  • Competition Teams (tournament brackets)
  • Position Meetings (position-specific)
  • Travel Bus Assignments
  • Locker Room Sections
  • Special Teams Units
• Template Management:
  • Edit ANY template (including defaults)
  • Delete ANY template
  • Restore default templates if needed
  • Create custom templates from existing groups

Group Features:

• Visual Management:
  • Color-coded groups for quick identification
  • Drag-and-drop player assignment (in edit mode)
  • Group timeline/cards view
  • Player count badges
• Metadata Tracking:
  • Meeting times and locations
  • Coach assignments
  • Purpose/notes for each group
• Export Options:
  • CSV export of all groups with player lists
  • Shareable formats for assistant coaches
  • Print-ready group sheets

Use Cases:

• Practice station rotations
• Academic study groups by GPA
• Bus/travel assignments
• Hotel room lists
• Equipment distribution groups
• Special teams units
• Conditioning groups
• Competition/tournament teams
• Accountability partnerships
• Position meeting rooms

Integration Potential:

• Future link to Personnel Manager for depth chart sync
• Practice Plans can use roster groups for period organization
• Export groups for use in practice scripts

9. Shifts & Motions (ShiftsMotions.tsx)

Purpose: Manage pre-snap adjustments and their installation status

Key Features:

• Shift Management: Multi-player pre-snap movements
• Motion Management: Individual player movements
• Installation Tracking: Track which adjustments are game-ready

10. Excel Integration (ExcelIntegration.tsx)

Purpose: Revolutionary spreadsheet-like interface that bridges digital play building with Excel workflows, featuring advanced multi-cell selection, inline editing, and seamless Play Library integration

Core Philosophy: Transform the Excel Integration from a simple import/export tool into a full-featured spreadsheet application specifically designed for football play management, combining the familiar Excel experience with football-specific intelligence.

Key Features:

🔥 Advanced Multi-Cell Selection System:

• Mouse Drag Selection: Click and drag across cells exactly like Excel for range selection
• Shift+Click Range Selection: Click first cell, then Shift+Click last cell to select entire range
• Ctrl+Click Multi-Select: Add or remove individual cells from selection with Ctrl+Click
• Shift+Arrow Keyboard Selection: Extend selection using Shift+Arrow keys for precise control
• Visual Selection Highlighting: Primary cell (dark blue outline) vs secondary cells (light blue background)
• Cross-Column Selection: Select across both left and right hash columns simultaneously

✏️ Inline Editing Capabilities:

• Double-Click to Edit: Double-click any cell to start inline editing mode
• F2 Keyboard Shortcut: Standard Excel-style editing with F2 key
• Enter/Escape Handling: Enter saves changes, Escape cancels editing
• Auto-Flip Integration: In pair mode, editing automatically generates flipped plays in opposite column
• Real-Time Validation: Uses existing parsePlayString() for live play validation
• Smart Hash Assignment: Automatically assigns L/R hash based on column position

📋 Enhanced Copy/Paste System:

• Ctrl+C Keyboard Shortcut: Copy selected cells using standard keyboard shortcut
• Multi-Cell Copy Support:
  • Single cell: Copies just that cell's content
  • Multiple cells: Creates tab-delimited format perfect for Excel
  • Range selection: Maintains grid structure with proper formatting
• Smart Paste Detection:
  • Multi-column paste (tab-delimited) for full Excel compatibility
  • Single-column paste with auto-flip capability
  • Multi-line paste for importing multiple plays at once
• Context-Aware Auto-Flip: Pasting left plays automatically generates right flips in pair mode

📚 Play Library Integration:

• "Add to Play Library" Button: Prominent orange button (first in toolbar) for instant library addition
• Bulk Library Addition: Scans all rows and adds every generated/pasted play to permanent library
• Unique ID Generation: Each play gets proper UUID and required metadata
• Toast Notifications: Success/warning messages with play count feedback instead of intrusive alerts
• Data Integrity: Ensures all required fields with smart defaults (hash positions, formations, concepts)

🎯 Advanced User Experience:

• Scrollable Toolbar: Horizontal scrolling prevents button overflow on smaller screens
• Whitespace-Nowrap Protection: Buttons maintain text integrity and don't wrap
• Global Mouse Handling: Proper drag selection behavior across the entire grid
• Selection State Persistence: Maintains selection across different operations
• Keyboard Navigation Enhancement: Arrow keys with Shift for selection, standard editing shortcuts

Intelligent Paste Detection (Enhanced):

• Multi-Format Recognition: Automatically detects play calls, personnel groups, formations, and individual plays
• Smart Parsing: Handles various paste formats from Excel, Word, or direct typing with improved error handling
• Context Awareness: Understands football terminology and structures data appropriately
• Multi-Cell Range Handling: Processes large Excel ranges efficiently with progress feedback

Bidirectional Excel Integration (Enhanced):

• Export to Excel: Generate formatted spreadsheets with plays organized by columns, personnel, or practice periods
• Import from Excel: Paste plays from Excel worksheets directly with multi-cell support
• Format Preservation: Maintains play structure and organization when moving between systems
• Bulk Operations: Handle large quantities of plays efficiently with visual feedback

Advanced Play Organization:

• Column-Based Sorting: Automatically organize plays into columns based on personnel, formation, or concept type
• Smart Placement: Intelligent positioning of plays within the spreadsheet structure
• Formation Auto-Detection: Recognizes formation patterns and suggests appropriate columns
• Duplicate Management: Handles repeated plays with user-defined preferences

Call Sheet Generation:

• Professional Formatting: Export plays in coach-ready call sheet formats
• Customizable Templates: Multiple layout options for different coaching preferences
• Practice Integration: Direct export of practice scripts to Excel for printing and distribution
• Game Planning: Generate game-ready call sheets with organized play categories

Collaborative Features:

• Coach Sharing: Easy sharing of play scripts and call sheets with assistant coaches
• Version Control: Track changes and updates to play collections
• Template System: Reusable Excel templates for consistent formatting
• Multi-User Workflow: Support for coaching staff collaboration through Excel

Data Validation (Enhanced):

• Football Rules Engine: Validates plays against football logic and system rules
• Concept Verification: Ensures all concepts exist in the system before import
• Personnel Matching: Validates personnel groups and position assignments
• Error Reporting: Detailed feedback on import/export issues with suggested fixes
• Real-Time Play Validation: Inline editing includes live validation and error feedback

Enhanced Integration Points:

• Play Library: Direct integration with bulk addition capabilities and unique ID management
• Practice Scripts: Export practice plans to Excel for physical distribution
• Personnel Manager: Sync personnel data with Excel depth charts
• Concept Library: Validate imported plays against existing concept database
• Play Generator: Seamless integration with generated plays for immediate editing and library addition

User Workflow Enhancement:

1. Generate or paste plays using the advanced Play Generator or Excel import
2. Select multiple cells using mouse drag, Shift+Click, or Ctrl+Click for precise control
3. Edit plays inline with double-click or F2 for real-time modifications
4. Copy selections with Ctrl+C for external use in Excel or other applications
5. Add to Play Library with single orange button click for permanent storage and organization

Technical Architecture:

• State Management: Complete overhaul from single selection to advanced multi-selection system
• Event Coordination: Sophisticated mouse, keyboard, and paste event handling
• Data Integrity: Maintains play data consistency across all operations
• Performance Optimization: Efficient handling of large play collections and multi-cell operations

11. Play Type Auto-Classification System

Purpose: Intelligent automatic categorization of plays as PASS, RUN, or RPO based on offensive concept analysis, eliminating manual classification while maintaining coaching flexibility

Core Philosophy: Leverage the coach's existing concept classifications (pass/run/protection/blocking) to automatically determine play types using football-specific logic that reflects modern offensive terminology and RPO integration.

Auto-Classification Logic:

PASS Play Detection:

• Protection Primary: Any play with a protection concept as the primary tag (SCAT LEFT, JET, QUICK, etc.)
• Pass Concepts Present: Plays containing pass concepts in left or right tag positions
• Pure Passing: Plays without primary tags but containing pass concepts

RUN Play Detection:

• Run Primary + Blocking Only: Run concepts as primary with only blocking concepts in tag positions
• Pure Run Execution: Traditional running plays with blocking support only
• No Pass Elements: Confirmed absence of pass concepts in any tag positions

RPO Play Detection:

• Run Primary Alone: Run primary concepts without any tags (recognizes base RPO structure)
• Run + Pass Combination: Run primary concepts combined with pass concepts in tags
• Modern Offensive Integration: Acknowledges that standalone run primaries include built-in pass options

Intelligence Features:

Concept-Based Analysis:

• Existing Classifications: Uses coach's pre-existing concept type definitions
• Football Logic: Applies real offensive coordinator decision-making patterns
• Contextual Understanding: Recognizes modern offensive evolution and RPO prevalence

Automatic Processing:

• Real-Time Classification: Automatically categorizes plays as they're created
• Bulk Processing: Classifies existing play libraries on system load
• Import Intelligence: Auto-classifies imported plays while respecting manual overrides
• Generation Integration: Applies classification to all generated plays

Manual Override Capability:

• Coach Control: Sortable dropdown in Play Library for manual adjustment
• Visual Indicators: Clear display of current classification with edit capability
• Preservation: Manual changes are preserved and not overwritten by auto-classification
• Flexibility: System adapts to coaching preferences and special situations

System Integration:

Comprehensive Coverage:

• Play Builder: Auto-classifies when saving manually created plays
• Play Generator: Applies classification to all generated play variations
• CSV Import/Export: Handles play type data in import/export workflows
• Play Library: Sortable column with immediate manual edit capability

Performance Benefits:

• Instant Organization: Immediate play type sorting and filtering
• Practice Planning: Filter practice scripts by play type for focused periods
• Game Planning: Quickly identify play types for situational game planning
• Analytics Ready: Prepared for future AI integration and advanced analytics

Technical Implementation:

• Smart Defaults: Classified as RPO when determination is unclear (reflects modern offense)
• Backward Compatible: Works with all existing plays without data migration
• Rule-Based Logic: Transparent, predictable classification rules
• Coach-Centric Design: Reflects actual coaching decision patterns and terminology

Fundamental Football Rules Implemented

Y-Strength System

• Y is ALWAYS in the game - Y determines formation strength
• Y position sets strength: Y's alignment determines Right/Left/Rip/Liz
• All players key off Y: Formation strength affects all player alignments

Player Position Rules

• X is ALWAYS on the LEFT, Z is ALWAYS on the RIGHT (except slot calls)
• Slot Calls Exception:
  • SLOT RIGHT: Z moves to #2 slot on left side
  • SLOT LEFT: X moves to #2 slot on right side

Concept Architecture

• All concepts are 2-man concepts by default
• Individual assignments modify the extra player(s)
• Concept nature drives player recognition
• Left-to-right calling convention: Individual assignments called before concept names

Personnel System Logic

• Personnel groups define adjusting players
• Adjusting players provide flexibility within concepts
• Personnel yelled from sideline, not signaled
• Each group has default formation but maintains flexibility

Hash System Integration

5-Hash Positions

• L (Left hash)
• LM (Left Middle)
• M (Middle)
• RM (Right Middle)
• R (Right hash)

Hash Considerations

• Field/Boundary Impact: Hash position affects formation strength preferences
• Y Tendency: Y typically to field, right if ball in middle (but flexible)
• Game Planning: Hash distribution affects defensive keys and play selection

State Management System

Core Data Structures

interface PlayScripterState {
  // Main data arrays
  concepts: Concept[]
  formations: Formation[]
  shifts: Shift[]
  motions: Motion[]
  playCalls: PlayCall[]
  practiceScripts: PracticeScript[]
  practiceTemplates: PracticeTemplate[]
  practicePlans: PracticePlan[]
  personnelGroups: PersonnelGroup[]
  personnelDepthCharts: PersonnelDepthChart[]
  
  // Dynamic customization
  customOptions: {
    formationStrengths: string[]
    formationTypes: string[]
    formationModifications: string[]
  }
  
  // Full CRUD operations for all entities
}

Advanced Type System

// Core position types
type PlayerPosition = 'LT' | 'LG' | 'C' | 'RG' | 'RT' | 'Q' | 'B' | 'A' | 'F' | 'Y' | 'H' | 'X' | 'Z' | 'T' | 'W'
type HashPosition = 'L' | 'LM' | 'M' | 'RM' | 'R'
type PersonnelCode = '21' | '20' | '11' | '22' | '10' | '00' | '01' | '23'

// Complete play call structure
interface PlayCall {
  id: string
  personnelGroupId?: string
  hash?: HashPosition
  formationStrength?: FormationStrength
  formation: FormationType
  formationModification?: FormationModification
  shift?: Shift
  motion?: Motion
  leftTag?: Concept
  leftTag2?: { player: PlayerPosition; assignment: string }
  primaryTag: Concept
  rightTag?: Concept
  rightTag2?: { player: PlayerPosition; assignment: string }
  notes?: string
}

// Personnel system
interface PersonnelGroup {
  id: string
  name: PersonnelName
  code: PersonnelCode
  adjustingPlayers: PlayerPosition[]
  availablePositions?: PlayerPosition[] // Which positions exist in this personnel
  replacementRules?: Array<{
    replaced: PlayerPosition
    replacedBy: PlayerPosition
  }>
  defaultFormation: {
    strength: FormationStrength
    type: FormationType
    modification?: FormationModification
  }
  description?: string
}

// Depth chart system
interface PersonnelDepthChart {
  id: string
  personnelGroupId: string
  position: PlayerPosition
  players: string[] // Unlimited depth
}

Key System Behaviors

Play Call Generation

Complete Format: ACE RIGHT FAR HAWAII ZIPPER GUM

• Personnel name leads the call (matches coaching language)
• Hash integrated but not displayed in call string (tracking purposes)
• Individual assignments precede concept names
• Maintains left-to-right order regardless of formation changes

Formation Flip Logic

1. Strength Flip: Right ↔ Left, Rip ↔ Liz
2. Slot Handling: Slot Right ↔ Slot Left
3. Position Preservation: X stays left, Z stays right
4. Order Maintenance: Play call sequence unchanged

Modular Flexibility

• Component Independence: Each element (personnel, formation, concept) stands alone
• Infinite Combinations: Any personnel + any formation + any concept + any hash
• Override Capability: Smart defaults with full manual override
• Custom Extensions: Add new options without system limitations

Advanced Features

Practice Script Intelligence

• Concept Rep Control: Set minimum/maximum repetitions for each concept
• Hash Distribution: Balance field/boundary/middle positioning
• Installation Filtering: Only include game-ready concepts
• Thoughtful Randomization: Random within coach-defined constraints

Personnel Management

• Dual Group System: Base + "2" versions for expanded rosters
• Position Calculation: Automatic position determination based on personnel code
• Depth Chart Flexibility: Unlimited players per position
• Sharing Capability: Player-accessible depth charts

Formation Customization

• Dynamic Options: Add formations, strengths, modifications in real-time
• Visual Positioning: Drag-and-drop player alignment
• Tag Box Integration: Visual zones determine concept applicability
• Template System: Reusable formation patterns

Export and Integration

Practice Scripts Export

• Formatted Call Sheets: Professional practice script formatting
• Metadata Integration: Date, situation, period information
• Play Numbering: Sequential numbering with complete play calls
• Notes Section: Additional practice information

Data Persistence

• Local Storage: All data persists between sessions
• Import/Export: Full system backup and restore capability
• Cross-Session: Maintains state across browser sessions

Development Architecture

Component Organization

src/
├── components/
│   ├── ConceptLibrary.tsx      # Concept management
│   ├── FormationSystem.tsx     # Formation strengths and types
│   ├── PersonnelManagerWithBigBoard.tsx # Integrated Big Board + Personnel system
│   ├── RosterManager.tsx       # Player roster management
│   ├── GroupBuilder.tsx        # Dynamic group creation
│   ├── PlayBuilder.tsx         # Central play creation hub
│   ├── PlayGenerator.tsx       # Advanced play generation engine
│   ├── PlayGeneratorSimple.tsx # Standalone play generator page
│   ├── PlayLibrary.tsx         # Play storage and management with auto-classification
│   ├── ExcelIntegration.tsx    # Bidirectional Excel integration system
│   ├── PracticeScripts.tsx     # Single-period script generation
│   ├── PracticePlans.tsx       # Multi-period practice management
│   ├── PracticePlanBuilder.tsx # Practice plan creation wizard
│   ├── PeriodGenerator.tsx     # Period-specific play generation
│   ├── PracticeTimeline.tsx    # Visual timeline component
│   ├── ShiftsMotions.tsx       # Pre-snap adjustments
│   └── Dashboard.tsx           # System overview
├── store/
│   └── useStore.ts            # Zustand state management
├── types/
│   └── index.ts               # TypeScript definitions
├── data/
│   ├── practiceTemplates.ts   # Default practice templates
│   └── groupTemplates.ts      # Default group templates
├── utils/
│   └── practicePlanExport.ts  # Multi-format export utilities
└── main.tsx                   # Application entry

Key Development Principles

1. Modularity First: Every component operates independently
2. Coach Flexibility: Never constrain creative play calling
3. Football Accuracy: Implements real football rules and logic
4. Scalability: Handles program-level complexity
5. Usability: Intuitive for non-technical coaches

System Capabilities Summary

Personnel Management with Big Board

✅ Revolutionary east-west layout with Big Board (left) and Personnel Groups (right) ✅ Master offensive roster with complete player profiles and position organization ✅ Advanced drag & drop system with three modes: within-position reordering, cross-position movement, and copy-to-depth-charts ✅ Complete personnel group system (18 groups) with unlimited depth charts per position per group ✅ Adjusting player logic with replacement rules and position management ✅ Personnel group creation, editing, deletion with safety features (reset disabled) ✅ Visual feedback with opacity changes, drop indicators, and bold player names ✅ Independent scrolling panels for maximum accessibility and workflow efficiency

Roster Management

✅ Complete player profiles with contact, physical, and academic data ✅ Dynamic custom options for positions, grades, and tags ✅ CSV import/export for bulk roster management ✅ Advanced group generation with granular control ✅ Equal distribution algorithms for balanced groups ✅ 8 editable/deletable default templates ✅ Template management with restore functionality ✅ Quick group actions (by position, grade, side) ✅ Delete all groups functionality ✅ Color-coded visual group management ✅ Group metadata tracking (times, locations, coaches) ✅ Multi-format export options

Play Building

✅ 6-step modular play construction ✅ Personnel-first play calling (ACE RIGHT FAR...) ✅ 5-hash position system ✅ Formation flip with order preservation ✅ Individual assignment integration ✅ Custom formation options

Concept Management

✅ 4 concept types with installation tracking ✅ Tag box assignment system ✅ Multi-person vs individual concept logic ✅ Installation status filtering

Excel Integration

✅ Advanced Multi-Cell Selection: Mouse drag, Shift+Click, Ctrl+Click, and Shift+Arrow selection exactly like Excel ✅ Inline Editing System: Double-click or F2 to edit cells with Enter/Escape handling and auto-flip integration ✅ Enhanced Copy/Paste: Ctrl+C keyboard shortcut, multi-cell copy support, and smart paste detection with auto-flip ✅ Play Library Integration: Orange "Add to Play Library" button for bulk addition with toast notifications and unique ID generation ✅ Advanced User Experience: Scrollable toolbar, visual selection highlighting, and global mouse handling ✅ Bidirectional data flow between app and Excel spreadsheets with multi-cell range support ✅ Intelligent paste detection for plays, personnel, formations with improved error handling ✅ Smart parsing with context awareness and multi-cell range processing ✅ Advanced play organization with column-based sorting and formation auto-detection ✅ Professional call sheet generation with customizable templates and practice integration ✅ Collaborative features for coaching staff workflow with version control ✅ Data validation with football rules engine and real-time play validation ✅ Comprehensive integration with Play Library, Practice Scripts, Personnel Manager, and Play Generator

Play Type Auto-Classification

✅ Intelligent automatic categorization as PASS, RUN, or RPO ✅ Concept-based analysis using existing coach classifications ✅ Football-specific logic reflecting modern offensive terminology ✅ Real-time classification for new plays and bulk processing for existing ✅ Manual override capability with sortable Play Library column ✅ Comprehensive integration across all play creation methods ✅ CSV import/export with PLAY TYPE column ✅ Backwards compatible with all existing plays

Practice Generation

✅ Single-period concept-driven script generation ✅ Multi-period practice plan system with visual timeline ✅ Advanced period generation with sophisticated filtering ✅ 6 pre-built practice templates (Install, Gameweek, Competition, etc.) ✅ Installation status filtering with debug logging ✅ Hash distribution patterns (6 different distributions) ✅ Concept distribution targets with percentage control ✅ Repetition control with smart play pool management ✅ Multi-format export (CSV Master Script, Period Cards, Text, JSON) ✅ Real-time analytics and progress tracking ✅ Drag-and-drop period reordering ✅ Metadata tracking and filtering integration

Formation System

❌ Visual formation builder (temporarily removed) ❌ Y-strength visual implementation (temporarily removed) ❌ Tag box zone system (temporarily removed) ❌ Drag-and-drop positioning (temporarily removed) ⚠️ Text-based formation selection still functional in Play Builder

Recent Major Updates (January 2025)

Roster Management System ✅ COMPLETED

A comprehensive player roster and group management system that transforms team organization:

Player Management:

• Complete player profiles with 14+ data fields
• Dynamic custom options for positions, grades, tags
• CSV import/export for bulk operations
• Grid and list view modes
• Advanced filtering and search

Group Generation Engine:

• Granular control with 5 balance methods
• Equal distribution algorithms
• Quick groups by position/grade/side
• Advanced options for precise control
• Delete all groups functionality

Template System:

• 8 default templates (all editable/deletable)
• Template editor with all parameters
• Restore defaults option
• Custom template creation

Integration Points:

• Standalone but ready for Personnel Manager sync
• Export groups for practice organization
• CSV compatibility with existing systems

Recent Major Updates (August 2025)

Big Board Personnel Management System ✅ COMPLETED

A revolutionary overhaul of the Personnel Manager that transforms roster management into a powerful, visual drag-and-drop experience:

East-West Layout Redesign:

• Left Panel (1/3): Big Board with master offensive roster
• Right Panel (2/3): Personnel Groups with depth charts
• Independent scrolling for each panel eliminates page constraints
• Simultaneous visibility of both systems for seamless workflow

Big Board Features:

• Complete player profiles with jersey numbers, year, height, weight
• Position-based organization across all offensive positions
• Advanced drag & drop with three modes:
  • Within position reordering (drag up/down in same position)
  • Cross-position movement (drag between position groups)
  • Copy to depth charts (drag to personnel groups)
• Visual feedback with opacity changes and animated drop indicators
• Compact 2-column design optimized for space efficiency
• Inline editing for quick player updates

Enhanced Personnel Integration:

• Bold player names in depth charts for improved readability
• Precise drop targeting with blue line indicators
• Safety features including disabled reset button to prevent accidents
• Maintains all existing functionality while adding visual management layer

Technical Improvements:

• Fixed reordering logic for accurate within-position player arrangement
• Smart index calculation that properly handles drag operations
• Data persistence with displayOrder tracking for consistent sorting
• Responsive design that adapts to different screen sizes

Play Type Auto-Classification System ✅ COMPLETED

A sophisticated intelligent play categorization system that automatically classifies plays as PASS, RUN, or RPO based on concept analysis:

Intelligent Classification Logic:

• PASS Detection: Protection primaries OR pass concepts in tags
• RUN Detection: Run primary + ONLY blocking tags (pure runs)
• RPO Detection: Run primary alone OR run primary + pass concepts

Key Features:

• Concept-Based Analysis: Uses existing coach concept classifications (pass/run/protection/blocking)
• Football Intelligence: Recognizes that standalone run primaries = RPOs in modern offense
• Manual Override: Sortable dropdown in Play Library for coach adjustments
• Comprehensive Integration: Auto-classifies in Play Builder, Play Generator, CSV import, and existing plays

System Implementation:

• Real-Time Processing: Classifies plays as they're created
• Bulk Classification: Processes existing play libraries on first load
• Preservation: Manual changes never overwritten by auto-classification
• CSV Integration: Includes PLAY TYPE column in import/export

Files Modified:

• /src/types/index.ts - Added playType field to PlayCall interface
• /src/components/PlayLibrary.tsx - Added sortable Play Type column with auto-classification
• /src/components/PlayBuilder.tsx - Auto-classifies on save
• /src/components/PlayGeneratorSimple.tsx - Auto-classifies generated plays

Recent Major Updates (August 2025) - Previous Updates

Multi-Period Practice Plan System ✅ COMPLETED

The revolutionary practice planning system has been fully implemented with these capabilities:

Practice Plan Management:

• Complete multi-period practice plans with visual timeline
• 4-step wizard: Template → Details → Periods → Review
• 6 pre-built templates with smart defaults
• Drag-and-drop period reordering with real-time updates

Advanced Period Generation:

• Sophisticated filtering: Personnel, concepts, metadata, installation status
• Hash distribution patterns: Balanced, Field Heavy, Boundary, Middle, Base, No Middle
• Concept distribution targets with percentage control
• Smart repetition control with play pool management
• Advanced settings: Required/forbidden concepts, max plays per concept

Visual Timeline & Analytics:

• Proportional duration bars with completion indicators
• Real-time analytics: Concept frequency, personnel distribution, hash patterns
• Progress tracking with visual indicators
• Hover tooltips with detailed period information

Multi-Format Export System:

• Master Script (CSV): Complete practice with play numbers and hash positions
• Period Cards (CSV): Individual files for each period
• Simple Text: Clean format for coaching staff
• JSON Backup: Complete practice plan data

User Experience Enhancements:

• Card-based practice plan overview with statistics
• Period preview with first 3 plays displayed
• Export dropdown menus for each practice plan
• Practice plan details modal with complete play lists

Future Enhancement Opportunities

Advanced Script Generation

• Concept Rep Ranges: "Run Hawaii 3-5 times" - precise repetition targets
• Situation Packages: Red zone, third down filtering - situational practice focus
• Opponent Integration: Game-specific adjustments based on scouting
• Progressive Installation: Track concept installation over time

Formation Intelligence

• True Flip System: Concepts flip with formations (ZIPPER ↔ ZULU)
• Directional Concept Mapping: R-word ↔ L-word protection flips
• Formation Tendencies: Track what's been shown to opponents
• Visual Formation Builder: Re-implement with systematic constraints

Advanced Analytics & AI Integration

• Usage Tracking: Concept and formation frequency analysis
• Installation Progress: Weekly installation reporting with completion metrics
• Player Load: Snap count distribution across personnel groups
• Game Plan Analysis: Weekly game plan comparison and tendency tracking
• AI-Powered Suggestions: Smart play generation based on practice history
• Predictive Analytics: Success rate predictions based on metadata

This system represents the evolution of football coaching from traditional paper playbooks to comprehensive digital management platforms. It maintains the fundamental football principles while leveraging technology to enhance organization, flexibility, and game preparation efficiency.

The app is designed for elite football programs that need to manage complex offensive systems while maintaining the modularity and flexibility required for high-level play calling and game planning.

System Updates Summary (January 2025)

Critical Understanding: Play Call Structure

The Immutable Order

The play call structure order NEVER CHANGES. This is fundamental to the system:

[Personnel] [Strength] [Formation] [Modification] [Shift] [Motion] [Left Ind Assign] [Left Tag] [Primary Tag] [B Assignment] [Right Ind Assign] [Right Tag]

Component Breakdown with Examples

Using the play: ACE RIP TRIPS BUNCH B TAXI Z FLY H STICK HAWAII ZIPPER Y STREAK CAVS

1. Personnel: ACE - The personnel group (21 personnel)
2. Formation Strength: RIP - Y position on right
3. Formation Type: TRIPS - The base formation
4. Formation Modification: BUNCH - How the formation is modified
5. Shift: B TAXI - Pre-snap movement (B player runs TAXI shift)
6. Motion: Z FLY - Motion at snap (Z player runs FLY motion)
7. Left Individual Assignment: H STICK - H player runs STICK route (overrides left tag)
8. Left Tag: HAWAII - Left side concept
9. Primary Tag: ZIPPER - Run/Protection concept (REQUIRED)
10. Right Individual Assignment: Y STREAK - Y player runs STREAK route (overrides right tag)
11. Right Tag: CAVS - Right side concept

Critical Rules

1. Individual assignments ALWAYS precede their tag on the same side
2. The structure order is IMMUTABLE - components may be empty but positions never change
3. Shifts are NOT individual assignments - they involve player movement names, not routes
4. Motions specify player + motion name format: "PLAYER MOTION_NAME"

Play Flipping Logic - Complete Understanding

What Flips

1. Formation Strength: All R-strengths ↔ L-strengths

   • RIGHT ↔ LEFT, RIP ↔ LIZ, REX ↔ LEX, ROC ↔ LOC, RAM ↔ LAM, RAY ↔ LOU
   • Case-insensitive comparison (handles RIP, Rip, rip)

2. Motion Players: ONLY X and Z flip

   • Z FLY → X FLY
   • Other players (B, H, Y, etc.) stay the same

3. Primary Tag: ONLY if it has a directionalPair property

   • ZIPPER ↔ ZULU, ROGER ↔ LARRY, etc.
   • Many primary tags don't flip (ISO, POWER, etc.)

4. Left/Right Content SWAPS:

   • Left tag moves to right position
   • Right tag moves to left position
   • Left individual assignments move to right position (with X/Z flip)
   • Right individual assignments move to left position (with X/Z flip)

What Does NOT Flip

1. Formation Type and Modification: Stay exactly the same
2. Shifts: No changes to shift or players involved
3. Tag Concepts: When swapping positions, concepts keep their names (HAWAII stays HAWAII)
4. Non-X/Z Players: In individual assignments, only X and Z flip

Flip Example - Complete Breakdown

Original: ACE RIP TRIPS BUNCH B TAXI Z FLY H STICK HAWAII ZIPPER Y STREAK CAVS Flipped: ACE LIZ TRIPS BUNCH B TAXI X FLY Y STREAK CAVS ZULU H STICK HAWAII

Detailed breakdown:

• ACE → ACE (personnel never changes)
• RIP → LIZ (strength flips)
• TRIPS BUNCH → TRIPS BUNCH (formation and mod stay same)
• B TAXI → B TAXI (shift stays same)
• Z FLY → X FLY (motion player flips)
• H STICK → Y STREAK (right ind assign moves to left position)
• HAWAII → CAVS (right tag moves to left position)
• ZIPPER → ZULU (primary flips via directionalPair)
• Y STREAK → H STICK (left ind assign moves to right position)
• CAVS → HAWAII (left tag moves to right position)

Dynamic Dropdown System - Complete Implementation

How It Works

1. Base Options: Hardcoded football terminology always appears

   • Formation Strengths: RIGHT, RIP, REX, ROC, RAM, RAY, LEFT, LIZ, LEX, LOC, LAM, LOU
   • Formation Types: WAIT, DEUCE, DOT, WING, FALSE, TRUE, SET, TROT, TRIPS, TREY, FAR, NEAR, EMPTY, ACE, QUAD
   • Modifications: BUNCH, ON, OVER, SQUEEZE, STACK, PINCH RT, PINCH LT, INCH RT, INCH LT, UGLY, WIDE, STACK LT, STACK RT

2. Dynamic Options: Pulled from actual data in the system

   • Unique values from existing formations
   • Custom options added by users
   • Values from imported plays

3. Import Behavior: When importing plays

   • New formation values are automatically added to custom options
   • These immediately appear in all dropdowns across the app
   • Personnel, concepts, shifts, and motions must pre-exist

4. Case Handling: All new values converted to UPPERCASE automatically

Personnel Dropdown Special Behavior

• Shows ONLY user-created personnel groups
• No automatic initialization of default groups
• Prevents unwanted "2" groups from reappearing
• "Reset to Default Groups" available for initial setup

Play Library Complete Column Structure

All 17 Columns (in display order)

1. Checkbox - Multi-select functionality
2. Play Call - Complete formatted string
3. Personnel - Personnel group name
4. Form Str - Formation strength
5. Formation - Formation type
6. Form Mod - Formation modification
7. Form Mod 2 - Second formation modification
8. Shift - Shift name
9. Motion - Player + motion name
10. Ind Assign (Left) - Left individual assignment
11. Left Tag - Left tag concept
12. Primary Tag - Primary tag (run/protection)
13. B Assign - B Assignment
14. Ind Assign (Right) - Right individual assignment
15. Right Tag - Right tag concept
16. Hash - Field position
17. Play Type - Auto-classified or manual (PASS/RUN/RPO)
18. Meta - Metadata indicator
19. Actions - Edit, Flip, Duplicate, Delete

Import/Export Behavior

• Export: All columns in CSV format with proper headers
• Import: Flexible header matching, automatic uppercase conversion
• Template: play-import-template.csv provided with examples
• Round-trip: Export format matches import format exactly

Key Learnings and Gotchas

1. Play Structure is Sacred

• The order of components in a play call NEVER changes
• Empty components are represented by absence, not reordering
• Individual assignments ALWAYS precede their respective tags

2. Shift vs Individual Assignment

• Shift: B TAXI - B player performs TAXI shift (pre-snap movement)
• Individual Assignment: B TAXI - B player runs TAXI route (post-snap)
• Context determines interpretation, position in structure is key

3. Formation Strength Determines Everything

• Y position sets the strength
• All other alignments key off this
• Flipping changes where Y aligns, affecting entire formation

4. Case Sensitivity Matters

• All storage should be UPPERCASE
• Comparisons must handle mixed case
• Display can use original case, logic uses uppercase

5. Personnel Groups are User-Controlled

• No automatic creation of default groups
• Import doesn't create new personnel groups
• This prevents unwanted data pollution

Recent Bug Fixes and Improvements (August 2025)

Practice Script Generation Fix - Installed Concepts Filter

Issue: Practice script generation with "Only include plays with installed concepts" was filtering out all plays even when concepts were marked as installed.

Root Cause: Plays stored concept references from when they were created, but these references didn't update when concepts were later marked as installed in the Concept Library.

Solution Implemented:

• Enhanced getConceptInstallStatus() function in PracticeScripts.tsx
• System now always looks up current concept installation status from the Concept Library
• Supports multiple concept reference formats (objects, IDs, names)
• Added debug logging to show which plays are filtered and why

How Installation Filter Works:

1. ALL concepts in a play must be installed for the play to be included
2. Checks left tag, primary tag, and right tag (if present)
3. Empty concept slots don't prevent inclusion
4. Always uses current installation status from Concept Library, not stale play data

Key Rules:

• Play with installed primary but uninstalled left/right tags = EXCLUDED
• Play with uninstalled primary but installed left/right tags = EXCLUDED
• Only plays where 100% of present concepts are installed = INCLUDED

Files Modified:

• /src/components/PracticeScripts.tsx - Enhanced concept lookup and filtering logic

Practice Script Generation Logic - Complete Understanding

Play Selection Process:

1. Initial Pool: Start with all plays in Play Library
2. Installation Filter (if checked): Include only plays where ALL concepts are marked as installed
3. Concept Focus Filter (optional): Include only plays containing selected concepts
4. Random Selection: Pick requested number of plays from filtered pool
5. Hash Distribution: Apply field positioning preferences (balanced, field, boundary, etc.)
6. Rep Constraints: Honor min/max repetition limits for concepts

Installation Status Lookup:

• Always queries current Concept Library for installation status
• Handles concept objects, IDs, and name-based lookups
• Prevents stale data issues from concept status changes
• Debug logging shows exactly why plays are included/excluded

Flexibility Options:

• Strict Mode: "Only include plays with installed concepts" - requires 100% concept installation
• Flexible Mode: Use "Filter by Concepts" instead - includes plays with at least one selected concept regardless of installation status

Multi-Period Practice Plan System - Complete Implementation Summary

System Overview

The multi-period practice plan system transforms the Football Play/Roster Manager from a single-period script generator into a comprehensive practice management platform. This system enables coaches to plan complete practice sessions with multiple focused periods, each with independent settings and sophisticated play generation.

Key Implementation Achievement

Successfully evolved from single period generator to comprehensive multi-period practice management - fulfilling the original user request to enable generation of "1 or more periods or a full practice."

Files Created/Modified:

1. /src/types/index.ts - Added comprehensive type definitions for practice plans, periods, templates, and analytics
2. /src/store/useStore.ts - Added CRUD operations for practice plans and templates with persistence
3. /src/data/practiceTemplates.ts - Created 6 default templates with helper functions
4. /src/components/PracticePlans.tsx - Main practice plan management interface with cards, details, and exports
5. /src/components/PracticePlanBuilder.tsx - 4-step wizard for creating complete practice plans
6. /src/components/PeriodGenerator.tsx - Advanced play generation modal for individual periods
7. /src/components/PracticeTimeline.tsx - Visual timeline with drag-and-drop and proportional duration bars
8. /src/utils/practicePlanExport.ts - Multi-format export system (CSV, JSON, Text, Period Cards)
9. /src/App.tsx - Added Practice Plans to main navigation

Critical System Features Implemented:

• Template-Driven Creation: 6 pre-built templates for different practice types
• Visual Timeline Management: Proportional duration display with drag-and-drop reordering
• Advanced Period Generation: Sophisticated filtering with metadata, personnel, and concept controls
• Multi-Format Export: 4 different export formats for various coaching needs
• Real-Time Analytics: Automatic analytics generation with concept frequency and distribution tracking
• Play Display Integration: Shows generated plays in practice plan details with "View All" functionality

Integration with Existing Systems:

• Play Library: Full integration with existing play filtering and selection
• Concept Library: Respects installation status and metadata filtering
• Personnel Manager: Uses personnel groups and position availability
• Practice Scripts: Maintains compatibility with single-period generation
• Export System: Consistent with existing CSV export patterns

User Feedback Resolution

The system successfully addressed all user concerns from the original conversation:

• "Configure doesn't click" → Replaced with intuitive "Generate Plays" button with green play icon
• "How do I shorten timelines" → Duration controls in period editing with 5-60 minute ranges
• "Generated plays not showing up" → Added visual play display in practice plan details and debugging
• "Installed only restriction" → Enhanced UI with warning indicators and easy removal buttons
• "Where to view generated plays" → Multiple display options including period cards and "View All" modals

The multi-period practice plan system represents a complete evolution of the practice generation capabilities, providing coaches with enterprise-level practice management while maintaining the simplicity and football accuracy of the original system.

important-instruction-reminders

Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.

Offensive System Structure & Play Calling Philosophy

Core Play Call Structure

Complete Play Call Order: [Personnel] [Hash] [Strength] [Formation] [Modification] [Shift] [Motion] [Left Ind Assign] [Left Tag] [Primary Tag] [B Assignment] [Right Ind Assign] [Right Tag]

Example: ACE RIP DEUCE B TAXI Z ORBIT H STICK CAVS ZIPPER A BRONCO Y STREAK HAWAII

• ACE: Personnel (21 personnel - 2 RB, 1 TE)
• RIP: Formation strength (Y on right)
• DEUCE: Formation type
• B TAXI: Shift (B player runs TAXI shift)
• Z ORBIT: Motion (Z player runs ORBIT motion)
• H STICK: Left individual assignment (H player runs STICK route)
• CAVS: Left tag concept
• ZIPPER: Primary tag concept (run/protection)
• A BRONCO: B Assignment (A player runs BRONCO concept)
• Y STREAK: Right individual assignment (Y player runs STREAK route)
• HAWAII: Right tag concept

Formation Strength System (Y-Strength)

Fundamental Rule: Y ALWAYS determines formation strength.

R-Strength Formations (Y on RIGHT):

• RIGHT: Y tight to right tackle
• RIP: Y in slot right
• REX: Y flexed right
• ROC: Y in rocket motion right
• RAM: Y at right end
• RAY: Y at right wing

L-Strength Formations (Y on LEFT):

• LEFT: Y tight to left tackle
• LIZ: Y in slot left
• LEX: Y flexed left
• LOC: Y in rocket motion left
• LAM: Y at left end
• LOU: Y at left wing

Player Position Rules

1. X is ALWAYS on the LEFT (except slot calls)
2. Z is ALWAYS on the RIGHT (except slot calls)
3. Y sets the strength - all other alignments key off Y position
4. Slot Exception:
   • SLOT RIGHT: Z moves to #2 slot on left side
   • SLOT LEFT: X moves to #2 slot on right side

Personnel System & Adjusting Players

Each personnel group has designated "adjusting players" who move to formation locations:

Key Personnel Groups:

• ACE (21): Adjusting: A - Default: RIGHT FAR
• QUAD (10): Adjusting: H - Default: RIGHT QUAD
• FLUSH (00): Adjusting: A,H - A replaces B - Default: RIP EMPTY

Formation Locations (based on strength):

When strength is RIGHT (Y on right):

• WAIT (far left) → DEUCE (left inside) → DOT (slot left) → WING → Y positions → TROT (slot right) → TRIPS (right inside) → TREY (far right)

When strength is LEFT (Y on left):

• TREY (far left) → TRIPS (left inside) → TROT (slot left) → Y positions → WING → DOT (slot right) → DEUCE (right inside) → WAIT (far right)

Concept Architecture

Primary Tags (Runs/Protections):

• Type: Run or Protection concepts only
• Directional Pairs: Many have opposing directions (ZIPPER ↔ ZULU, SCAT LEFT ↔ SCAT RIGHT)
• Always Required: Every play must have a primary tag

Left/Right Tags (Pass Concepts):

• Type: Pass concepts only
• No Directional Pairs: Stand alone concepts (HAWAII is HAWAII, BOW is BOW)
• Optional: Can be empty

Individual Assignments:

• Format: Player + Assignment (e.g., "B TAXI", "Z ORBIT")
• Always Precede Concepts: Individual assignments come before concept names in call order
• Any Player: Can assign to any position (LT, LG, C, RG, RT, Q, B, A, F, Y, H, X, Z, T, W)

Play Flipping Logic

What Flips:

1. Formation Strength: R ↔ L (RIP ↔ LIZ)
2. Primary Tags: Only if they have directionalPair property
3. X/Z Responsibilities: All individual assignments and motions
4. Tag Positions: Left concepts move right, right concepts move left

What Doesn't Flip:

1. Pass Concepts: Left/right tags keep same names when swapping positions
2. Personnel: Same personnel group
3. Formation Type: Same formation type (DEUCE stays DEUCE)

Hash System Integration

5-Hash Positions: L (Left hash) → LM (Left Middle) → M (Middle) → RM (Right Middle) → R (Right hash)

Hash position affects:

• Field/Boundary considerations
• Y tendency preferences
• Formation strength selection
• Defensive key recognition

Practice Script Generation Philosophy

• Concept-Driven: Select specific concepts to focus practice
• Installation Filtering: Only include "installed" concepts when filtered
• Thoughtful Randomization: Random within coach-defined constraints
• Rep Range Control: Honor min/max repetitions for each concept
• Hash Distribution: Balance field positioning

Play Library Import/Export System

Overview

The Play Library now includes comprehensive import/export functionality that allows coaches to:

• Export their entire play library as a CSV file with all play components
• Import plays from CSV files with flexible column mapping
• Use a standardized template for consistent data exchange

CSV File Structure

Column Headers (in order)

1. Play Call - The complete play call string (optional - will be generated if missing)
2. Personnel - Personnel group name (e.g., ACE, QUEEN, 2 JACK)
3. Form Str - Formation strength (e.g., RIGHT, RIP, LEFT, LIZ)
4. Formation - Formation type (e.g., FAR, DEUCE, TRIPS)
5. Form Mod - Formation modification (e.g., BUNCH, SQUEEZE, STACK RT)
6. Shift - Shift name (must match existing shifts in system)
7. Motion - Motion in format "PLAYER MOTION_NAME" (e.g., "Z ORBIT", "A JET")
8. Ind Assign (Left) - Left individual assignment "PLAYER ASSIGNMENT" (e.g., "B TAXI")
9. Left Tag - Left tag concept name
10. Primary Tag - Primary tag concept name (REQUIRED)
11. B Assign - B Assignment "PLAYER ASSIGNMENT" (e.g., "A BRONCO")
12. Ind Assign (Right) - Right individual assignment "PLAYER ASSIGNMENT"
13. Right Tag - Right tag concept name
14. Hash - Hash position (L, LM, M, RM, R)

Import Rules

• Case Insensitive: All values are automatically converted to uppercase
• Flexible Headers: System recognizes variations (e.g., "FORM STR" or "FORMATION STRENGTH")
• Entity Matching: Personnel groups, concepts, shifts, and motions must exist in the system
• Motion Format: "PLAYER MOTION_NAME" where player is a valid position
• Individual Assignment Format: "PLAYER ASSIGNMENT" where player is a valid position
• Missing Values: Empty cells are handled gracefully with appropriate defaults
• Primary Tag Required: Every play must have a primary tag (run/protection concept)
• Dynamic Dropdown Updates: When importing plays with new formation values:
  • New formation strengths are added to custom options (if not base options)
  • New formation types are added to custom options (if not base options)
  • New formation modifications are added to custom options (if not base options)
  • These new values immediately appear in all dropdowns throughout the app

Export Features

• Complete Data: Exports all play components in the correct column structure
• CSV Format: Compatible with Excel, Google Sheets, and other spreadsheet applications
• Quoted Values: All values are properly quoted to handle special characters
• Date Stamped: Export files include the current date in the filename

Template File

A template file play-import-template.csv is included in the project folder with example plays demonstrating:

• Various personnel groups and formations
• Proper motion and shift formatting
• Individual assignment syntax
• All hash positions
• Complex multi-component plays

How to Use Import/Export

Exporting Plays

1. Navigate to Play Library
2. Apply any filters to export specific plays (optional)
3. Click "Export Library" button (green)
4. File downloads as play-library-YYYY-MM-DD.csv

Importing Plays

1. Prepare CSV file matching the template structure
2. Ensure all referenced entities exist in system:
   • Personnel groups must be created first
   • Concepts must exist in Concept Library
   • Shifts/Motions must be defined
3. Click "Import Plays" button (purple) in Play Library
4. Select your CSV file
5. System will show import results:
   • Number of plays successfully imported
   • Number of errors (with console logs for debugging)

Best Practices

1. Export First: Export your current library to see the exact format
2. Check Entities: Verify all personnel groups, concepts, shifts, and motions exist before import
3. Use Template: Start with the provided template file for correct formatting
4. Test Small: Import a few plays first to verify format
5. Uppercase Consistency: While import converts to uppercase, maintaining uppercase in source files prevents confusion

Recent Updates (August 2025) - Metadata System & Performance

Complete Metadata System Implementation

Purpose: Enable coaches to track ANY custom data about concepts and plays for future AI-powered analytics and smarter play calling.

1. Concept Metadata System ✅

• Fully Customizable Fields: Create any field type (tags, numbers, percentages, booleans)
• Categories: Organize fields by category (Situation, Analytics, etc.)
• Dynamic UI: Collapsible sections, chip-based selection, inline editing
• Complete Integration:
  • CSV export/import with dynamic columns
  • Practice script filtering by metadata
  • Full system backup preserves all metadata

2. Play-Level Metadata System ✅

• Same Flexibility: All field types available for complete play calls
• Play Library Integration: Database icon shows metadata status (purple = has data)
• Modal Interface: Click to add/edit metadata for any play
• Full Import/Export: CSV includes all play metadata fields dynamically

3. Metadata Field Management ✅

In Settings Page:

• Concept Metadata Fields: View, delete, export, reset to defaults
• Play Metadata Fields: Separate management section with same features
• Data Summary: Shows count of metadata fields
• Export Field Definitions: Save your custom field structures

4. Practice Script Enhancements ✅

• Metadata Filtering: Filter by concept metadata values
• All Field Types: Supports tags, numbers, percentages, booleans
• Debug Logging: Console shows why plays are filtered
• Available Plays Count: Shows how many plays match current filters

5. Performance Optimization - Pagination ✅

Play Library Now Handles 2000+ Plays:

• Default: 100 plays per page (optimal performance)
• Options: 50, 100, 250, or 500 plays per page
• Smart Navigation: Page numbers, previous/next buttons
• Auto-Reset: Returns to page 1 when filtering
• Export Options: "Export Filtered" or "Export All"

How Metadata Works

Creating Fields

1. For Concepts: Edit any concept → Add Field button
2. For Plays: Click database icon on any play → Add Field button
3. In Settings: View all fields, delete unused ones

Field Types

• Tags: Multi-select options (e.g., "Red Zone", "3rd Down")
• Number: Any numeric value (e.g., Average Yards)
• Percentage: 0-100% values (e.g., Success Rate)
• Boolean: Yes/No toggles (e.g., Tempo Ready)

Data Flow

1. Add Metadata → Stored with concept/play
2. Export CSV → Dynamic columns for all fields
3. Import CSV → Recognizes [Category] Field Name format
4. Practice Scripts → Filter by any metadata value

Sample Metadata Fields

Concept Metadata (Teaching Focus)

{
  // Situation
  "downAndDistance": ["3rd-Short", "3rd-Medium"],
  "fieldPosition": ["Red Zone"],
  
  // Analytics  
  "explosivePotential": true,
  "expectedYards": 12,
  "successRate": 75
}

Play Metadata (Execution Focus)

{
  // Performance
  "practiceSuccess": 85,
  "gameSuccess": 90,
  "averageYards": 14,
  
  // Matchups
  "bestVsCoverage": ["Cover 2", "Cover 3"],
  "tempoReady": true,
  
  // Tracking
  "timesRun": 23,
  "lastUsed": "This Week"
}

Future AI Integration Ready

The metadata system creates a knowledge base where:

• Every practice adds performance data
• Every game refines success patterns
• Every field teaches the AI your terminology
• Every value builds predictive power

Future AI can answer:

• "Show me Red Zone plays with 80%+ success vs Cover 2"
• "Generate a 3rd down script using only tempo-ready plays"
• "What plays work best from left hash with these concepts?"

Recent Updates (August 2025) - Personnel Position Management & Source of Truth

Personnel Position Management System

Purpose: Define which player positions exist in each personnel group to ensure accurate play generation and prevent impossible player assignments.

Key Features:

1. Available Positions Field: Each personnel group now tracks which positions are actually on the field
2. Edit Interface: Checkbox grid in Personnel Manager to select active positions
3. Smart Defaults: System suggests appropriate positions based on personnel code
4. Play Generator Integration: Only generates plays using positions that exist in the selected personnel

How It Works:

1. Edit Personnel Group: Click edit button in Personnel Manager
2. Select Positions: Check boxes for all positions in that personnel (e.g., JUMBO has no X or Z)
3. Automatic Filtering: Play Generator only uses available positions for:
   • Shift players
   • Motion players (prefers perimeter players when available)
   • Individual assignments

Example Position Configurations:

• ACE (21): LT, LG, C, RG, RT, Q, B, A, F, Y, H, X, Z
• KING (22): LT, LG, C, RG, RT, Q, B, A, F, Y, T, Z (T replaces X)
• JUMBO (23): LT, LG, C, RG, RT, Q, B, A, F, Y, T, W (no X or Z)
• FLUSH (00): LT, LG, C, RG, RT, Q, H, X, Z (no RBs or TEs besides positions)

Sources of Truth Philosophy

Critical Update: The system now exclusively uses designated source pages for all data:

Official Sources:

1. Formation System → Formation Strengths & Formation Types
2. Shifts & Motions → Shifts, Motions, Formation Modifications
3. Concept Library → All offensive concepts
4. Personnel Manager → Personnel groups and position availability

What Changed:

• No More Mixed Data: Formation strengths can't appear as formation types
• No More Duplicates: Each component pulls from ONE authoritative source
• No More "LOC LEFT" Issues: Proper validation prevents multiple strengths

Developer Note:

The formations array and customOptions are maintained for UI functionality but are NOT sources of truth for dropdowns. Only the designated system pages provide authoritative data.

Recent Updates (August 5, 2025) - Play Generator and System Compatibility

Play Generator Implementation

Purpose: Revolutionary automated play generation system that transforms coaches from manual play builders into strategic coordinators.

Key Features:

1. Granular Component Control:

   • 16 individual checkboxes for complete customization
   • 100% reliable generation - if checkbox is checked, component ALWAYS generates
   • No more probability-based generation failures

2. Split Primary Tag Control:

   • Separate "Primary Tag (Run)" checkbox for run concepts only
   • Separate "Primary Tag (Protection)" checkbox for protection concepts only
   • Can select one, both, or neither for precise play type control

3. Advanced Filtering:

   • Installation status filter (All / Installed Only / Not Installed)
   • Concept type filters (Pass, Run, Protection, Blocking, etc.)
   • Specific concept selection - scrollable list with exact concept picking
   • Personnel group selection - choose which personnel to use

4. Dual Implementation:

   • Embedded in Play Builder (starts collapsed for clean interface)
   • Standalone page via menu (starts expanded for immediate use)
   • Both use identical generation logic

Component Fixes:

• Fixed component count display (was counting legacy primaryTag field)
• Ensured only selected components generate (no auto-assignment)
• Added metadata tracking for auto-added formations

Critical Bug Fixes

1. Play Library Crash with Optional Primary Tag

Issue: Play Library crashed when displaying plays without primary tags Solution: Added null checks throughout PlayLibrary.tsx for optional primaryTag Impact: System now handles partial plays gracefully

2. Individual Assignments Lost Between PlayBuilder and Library

Issue: "H ARROW" and other individual assignments disappeared when saving Root Cause: PlayBuilder used new array format but Library only read legacy format Solution:

• Convert new rightIndividualAssignments array to legacy rightTag2 format when saving
• Sync both formats for backward compatibility
• Update display logic to avoid duplicates

3. Formation Auto-Assignment in Generated Plays

Issue: Generated plays with only primary tag showed "DEUCE" as personnel Solution:

• Track auto-added formations with metadata
• Hide auto-formations from play call string display
• Maintain type system compatibility

UI/UX Improvements

1. Configurable Expansion States

• Play Builder's generator starts collapsed (clean interface)
• Standalone generator page starts expanded (ready to use)
• Controlled via startExpanded prop

2. Flip Button Integration

• Added to Play Generator interface
• Positioned between Copy and Save buttons
• Uses existing flip logic from Play Library

3. Visual Feedback

• Shows count of available concepts based on filters
• Real-time component count updates
• Clear disabled states for unavailable actions

System Compatibility Philosophy

Dual-System Support

The app maintains compatibility between:

1. Traditional Play Builder: Requires all components, enforces football rules
2. Play Generator: Allows partial plays, component-by-component generation

Key Design Decisions:

• Formation remains required in PlayCall interface for type safety
• Metadata tracks auto-additions to hide them from display
• Legacy formats maintained alongside new implementations
• Both systems coexist without breaking existing functionality

Data Format Compatibility:

• New individualAssignments arrays for modern UI
• Legacy leftTag2/rightTag2 for backward compatibility
• Automatic conversion between formats when saving
• Play Library reads legacy format for consistent display

Recent Updates (Context Window Session - July 31, 2025)

Bug Fixes and Improvements

1. Formation Modification 2 Display Fix

Issue: Additional Formation Modification (formationModification2) wasn't showing in play call preview. Solution: Added formationModification2 to generatePlayCallString function and flip logic. Impact: Now displays properly: ACE RIP TRIPS BUNCH STACK RIGHT where BUNCH is mod1 and STACK RIGHT is mod2.

2. SLOT Modification Positioning Fix

Issue: SLOT modifications weren't appearing before formation strength as intended. Solution: Updated play string generation to recognize "SLOT", "SLOT RIGHT", and "SLOT LEFT" as special modifications that appear before strength. Impact: Play calls now correctly show: ACE SLOT RIP TRIPS instead of ACE RIP TRIPS SLOT.

3. Motion Display Cleanup

Issue: Motions were displaying with player prefix (e.g., "Z BOLT", "Z BURN"). Solution: Removed player prefix from motion display in both ShiftsMotions and PlayBuilder components. Impact: Motions now show as generic names (BOLT, BURN, ORBIT) that can be assigned to any player.

4. Play Builder Dropdown Improvements

Issue: Duplicate entries in formation dropdowns and inability to delete options. Solutions Implemented:

• Created deduplicated dropdown lists combining base options + unique values + custom options
• Changed "custom options" sections to show ALL options (not just custom) with ability to delete non-base items
• Added "Clean Up Duplicates" button to remove any duplicate entries
• Fixed addCustomOption to prevent adding duplicates
• Base options (core football terms) are protected from deletion

5. Formation Modification "Add New" Fix

Issue: Adding new formation modifications wasn't working - items wouldn't appear in dropdown. Solution: Changed to create FormationMod objects instead of just adding to customOptions. Impact: New modifications now properly appear in dropdowns immediately after creation.

6. Hash Distribution Fix for Practice Scripts

Issue: All plays in practice scripts were showing as "M" (Middle) regardless of selected hash distribution. Solution: Modified script generation to create new play objects with assigned hash values instead of using original play objects. Impact: Hash distribution now works correctly:

• Balanced: Rotates through L, LM, M, RM, R
• Field Heavy: Avoids middle
• Boundary Heavy: L and R only
• Middle Heavy: LM, M, RM only
• BASE/NO MIDDLE: Follow specific patterns

Major System Updates (January 2025)

Play Flipping System Enhancement

Feature: Comprehensive play flipping system with correct football logic.

Critical Understanding:

• Formation Strength Flipping: All R-strength formations (RIGHT, RIP, REX, ROC, RAM, RAY) flip to L-strength formations (LEFT, LIZ, LEX, LOC, LAM, LOU)
• Y-Strength Rule: Y position determines formation strength - ALL R formations put Y on RIGHT, ALL L formations put Y on LEFT
• Primary Tag Flipping: ONLY primary tags (runs/protections) have directional pairs and flip concepts
• Left/Right Tag Swapping: Pass concepts in left/right tags ONLY swap positions - they don't flip concepts
• X/Z Player Flipping: X and Z switch all responsibilities (individual assignments, motions)

Correct Flip Logic:

1. Formation strength flips (RIP → LIZ)
2. Formation type and modification stay the same
3. Shifts stay the same (no player flipping)
4. Motions flip X/Z players only
5. ONLY primary tags flip if they have directionalPair property (ZIPPER → ZULU)
6. Left/right tags swap positions but keep same concepts (HAWAII stays HAWAII)
7. Individual assignments swap positions AND flip X/Z players

Play Call Structure Order (NEVER CHANGES): [Personnel] [Strength] [Formation] [Modification] [Shift] [Motion] [Left Ind Assign] [Left Tag] [Primary Tag] [B Assignment] [Right Ind Assign] [Right Tag]

Example:

• Original: RIP TRIPS BUNCH B TAXI Z FLY HAWAII ZIPPER H STREAK CAVS
• Flipped: LIZ TRIPS BUNCH B TAXI X FLY CAVS ZULU HAWAII

Breaking it down:

• RIP → LIZ (strength flips)
• TRIPS BUNCH (stays same)
• B TAXI (shift stays same)
• Z FLY → X FLY (motion player flips)
• (no left ind assign) → (no left ind assign)
• HAWAII → CAVS (tags swap positions)
• ZIPPER → ZULU (primary flips)
• H STREAK → (nothing) (ind assigns swap positions)
• CAVS → HAWAII (tags swap positions)

Play Library Enhancements

New Features:

• Multi-Select Functionality: Select multiple plays with checkboxes
• Create Scripts from Selection: Generate practice scripts from selected plays
• Inline Editing: Edit any play directly in the table with full form interface
• Enhanced Actions: Flip, Duplicate, Edit, Delete buttons for each play
• Left/Right Tag Columns: Visual display of all play components
• Export to CSV: Play library exports as spreadsheet-friendly CSV

Practice Script Export Enhancement

Change: Scripts now export as CSV instead of TXT format

• Better Organization: Separate columns for Play #, Hash, Personnel, Formation, Play Call
• Spreadsheet Ready: Opens directly in Excel/Google Sheets
• Metadata Included: Script details at top of CSV file
• Professional Format: Clean, sortable data for coaching staff

Individual Assignment Fix (January 2025)

Issue: Individual assignment fields in PlayBuilder were only visible when formations had players in tag boxes, making them dependent on formation selection. Solution: Removed conditional rendering dependency and made individual assignments always available in both Left Tag and Right Tag sections.

Changes Made:

• /src/components/PlayBuilder.tsx: Lines 700-746 and lines 800-846
• Removed {leftBoxPlayers.length > 0 && and {rightBoxPlayers.length > 0 && conditional wrappers
• Added all player positions (LT, LG, C, RG, RT, Q, B, A, F, Y, H, X, Z, T, W) as static options
• Individual assignments now always appear regardless of formation selection
• Maintains proper play call structure: Individual assignments precede concept names in call order

Impact: Coaches can now assign individual routes/assignments to any player position at any time, providing maximum flexibility in play design without being constrained by formation-specific tag boxes.

Dynamic Dropdown System (January 2025)

Purpose: Ensure all dropdown fields reflect actual data in the system rather than showing hardcoded options.

Changes Made:

1. Formation Dropdowns:

   • Base options are always shown (RIGHT, RIP, REX, etc. for strengths; DEUCE, TRIPS, etc. for types)
   • Additional options from existing formations are dynamically added
   • Custom options can be added on-the-fly
   • All new values are automatically converted to UPPERCASE

2. Personnel Dropdowns:

   • Only shows personnel groups actually created by the user
   • Removed automatic initialization of predefined groups
   • "Reset to Default Groups" button still available for initial setup

3. Formation Modifications:

   • Hardcoded base options: BUNCH, ON, OVER, SQUEEZE, STACK, PINCH RT, PINCH LT, INCH RT, INCH LT, UGLY, WIDE, STACK LT, STACK RT
   • Dynamic options from existing formations
   • Custom additions supported

Impact: System now accurately reflects user's actual data while maintaining essential football terminology as base options.

Play Library Enhancement (January 2025)

Purpose: Complete the Play Library with full import/export functionality and all play components visible.

New Features:

1. Complete Column Display:

   • All 15 columns now visible in Play Library table
   • Matches the complete play call structure from build to display
   • Smaller font and spacing to accommodate all columns

2. CSV Import Functionality:

   • Purple "Import Plays" button added
   • Flexible column header matching
   • Automatic uppercase conversion
   • Entity validation (personnel, concepts, shifts, motions must exist)
   • Import summary with success/error counts

3. Enhanced CSV Export:

   • Exports all play components in proper column order
   • Headers match import format for round-trip compatibility
   • Properly quoted values for spreadsheet compatibility

4. Template File:

   • play-import-template.csv provided with 10 example plays
   • Demonstrates all formatting requirements
   • Shows complex plays with multiple components

Impact: Coaches can now easily share plays between systems, import from spreadsheets, and maintain play libraries across multiple installations.

B Assignment Implementation (January 2025)

Purpose: Add dedicated B Assignment field for protection schemes where B assignments are part of the protection call.

Problem Solved: Protection schemes like SCAT LEFT/RIGHT needed B assignments to appear after the primary tag as part of the protection call (e.g., "SCAT LEFT B TEXAS" as a unit).

Implementation Details:

1. New Field Added: bAssignment field added to PlayCall interface
2. Proper Positioning: B assignments now appear immediately after primary tag in play calls
3. Dropdown Selection: B Assignment uses dropdown allowing selection from all available concepts
4. Flip Logic: B assignments stay with primary tag during flips (don't move or change sides)
5. Full Integration: Updated across all components:
   • PlayBuilder UI with concept dropdown
   • Play Library display and CSV import/export
   • Practice Scripts generation and export
   • Play string generation throughout system

Example:

• Play Call: ACE RIP DEUCE SCAT LEFT B TEXAS HAWAII
• Structure: Personnel + Formation + Primary Tag + B Assignment + Right Tag

Files Modified:

• /src/types/index.ts: Added bAssignment field to PlayCall interface
• /src/components/PlayBuilder.tsx: Added B Assignment UI section with concept dropdown
• /src/components/PlayLibrary.tsx: Added B ASSIGN column and CSV handling
• /src/components/PracticeScripts.tsx: Updated play string generation and flip logic

Shift Player Selection Implementation (January 2025)

Purpose: Allow coaches to specify which player performs each shift, similar to motion player selection.

Implementation Details:

1. New Field Added: shiftPlayer field added to PlayCall interface
2. Two-Column UI: Shift section converted to player dropdown + shift dropdown layout
3. Player Selection: Dropdown with all skill positions (Q, B, A, F, Y, H, X, Z, T, W)
4. Default Behavior: Defaults to 'B' if no player specified (maintains backward compatibility)
5. Flip Logic: X and Z players flip when play is flipped, other positions stay the same
6. Full Integration: Updated across all components for consistency

Example:

• Shift Display: "Z TAXI" (Z player runs TAXI shift)
• Play Call: ACE RIP DEUCE Z TAXI SCAT LEFT HAWAII

Files Modified:

• /src/types/index.ts: Added shiftPlayer field to PlayCall interface
• /src/components/PlayBuilder.tsx: Updated shift UI to two-column layout with player selection
• /src/components/PlayLibrary.tsx: Updated CSV import/export to handle shift players
• /src/components/PracticeScripts.tsx: Updated play string generation and flip logic

CSV Import/Export System Fixes (August 2025)

Purpose: Fix critical issues with CSV import/export to ensure clean round-trip data handling.

Problems Fixed:

1. Quote Escaping: Export was double-quoting all values, making files unusable for re-import
2. Header Mismatch: Export used "Primary Tag" while import expected "PRIMARY"
3. CSV Parsing: Import couldn't handle quoted values with commas properly
4. Trailing Spaces: Import wasn't trimming spaces from cell values

Solutions Implemented:

1. Proper CSV Escaping:

   • Only quote values when necessary (contains comma, newline, or quote)
   • Properly escape quotes within quoted values
   • Clean, standard CSV format

2. Header Consistency:

   • Export headers now match import expectations exactly
   • All headers in UPPERCASE: PLAY CALL,PERSONNEL,FORM STR,FORMATION,FORM MOD,SHIFT,MOTION,LEFT IND ASSIGN,LEFT TAG,PRIMARY,B ASSIGN,RIGHT IND ASSIGN,RIGHT TAG,HASH
   • System accepts both "IND ASSIGN" (twice) or "LEFT/RIGHT IND ASSIGN" formats

3. Smart CSV Parser:

   • Handles quoted values correctly
   • Respects escaped quotes
   • Automatically trims spaces
   • Supports standard CSV formats

Impact: Clean import → work in app → clean export → share/re-import without data loss

Smart Concept Import with Player Prefixes (August 2025)

Purpose: Allow imports to intelligently handle player letters attached to concepts (e.g., "A BRONCO", "Y HAWAII").

Problem Solved: Coaches naturally write plays with player assignments as part of concepts. The system needed to recognize that "A BRONCO" means player A runs the BRONCO concept.

Implementation Details:

1. Smart Matching: System recognizes valid player letters (Q, B, A, F, Y, H, X, Z, T, W) followed by a space and concept name
2. Concept Extraction: Strips player prefix to find base concept (e.g., "A BRONCO" → finds "BRONCO" concept)
3. Intelligent B Assignment: For primary tags with player prefixes, automatically populates B ASSIGN field
4. Universal Application: Works for all tag types (left, right, primary)

Examples:

• Import "A BRONCO" as primary → Finds "BRONCO" concept, sets B ASSIGN to "A"
• Import "Y HAWAII" as right tag → Finds "HAWAII" concept
• Import "B STICK" as left tag → Finds "STICK" concept
• Import "BRONCO" → Standard exact match, no player assignment

Coaching Philosophy Alignment: This update reflects the modern offensive principle that:

• Concepts are universal - Any player can execute any concept
• Flexibility is key - Players understand their role within each concept
• Simplicity in teaching - Teach movements, not rigid assignments
• Complexity in application - Same concept, multiple players, endless variations

Import Flexibility Enhancements

1. Personnel Groups: Play import allows plays without personnel groups - they will import successfully with undefined personnelGroupId and can be assigned personnel later.
2. Player-Prefixed Concepts: System intelligently handles concepts with player letters, supporting flexible offensive systems where any player can run any concept.
3. Format Flexibility: Import accepts multiple header formats and handles various CSV structures.

System Philosophy Update

Concept-Driven Offense

The Football Play/Roster Manager fully embraces modern offensive football philosophy where:

1. Concepts Are Universal: Base concepts (HAWAII, STICK, BRONCO) are taught as movements and principles, not player-specific plays
2. Maximum Flexibility: Any player can execute any concept based on alignment, personnel, and game situation
3. Player Intelligence: Players understand concepts contextually - they know their role within each concept
4. Simplified Teaching: Teach fewer concepts deeply rather than many plays superficially
5. Complex Application: Same concepts create infinite variety through different players, formations, and tags

This philosophy is now fully supported in the import/export system, allowing coaches to use their natural language (e.g., "A BRONCO") while maintaining systematic data structure.

Important Technical Notes

CSV Import/Export Headers

The system expects these exact headers for import (ALL CAPS):

PLAY CALL,PERSONNEL,FORM STR,FORMATION,FORM MOD,SHIFT,MOTION,LEFT IND ASSIGN,LEFT TAG,PRIMARY,B ASSIGN,RIGHT IND ASSIGN,RIGHT TAG,HASH

Alternative format also accepted:

PLAY CALL,PERSONNEL,FORM STR,FORMATION,FORM MOD,SHIFT,MOTION,IND ASSIGN,LEFT TAG,PRIMARY,B ASSIGN,IND ASSIGN,RIGHT TAG,HASH

Data Requirements

• Personnel groups, concepts, shifts, and motions must exist in the system before import
• PRIMARY field is required for all plays
• All values converted to UPPERCASE automatically
• Empty cells handled gracefully
• Player prefixes intelligently processed

Troubleshooting

Common Issues and Solutions

Formation Strength Duplication (e.g., "LOC LEFT")

Problem: Play Generator creates plays with two formation strengths like "ACE LOC LEFT DEUCE" Cause: Formation data mixed between strength and type dropdowns Solution: System now validates that formation strengths only appear in strength position and types only in type position

Invalid Player Assignments

Problem: Plays generated with players that don't exist in personnel (e.g., "JUMBO ... X STREAK") Cause: Play Generator wasn't aware of personnel-specific position constraints Solution: Use Personnel Manager to define available positions for each group - Play Generator will respect these

Missing Dropdowns Options

Problem: Formation options not appearing in dropdowns Cause: Data not properly added to source of truth pages Solution: Add formations via Formation System page, not through custom options

Play Import Failures

Problem: CSV import shows errors for valid-looking plays Cause: Referenced entities (personnel, concepts, shifts, motions) don't exist in system Solution: Create all referenced entities before importing plays

Depth Chart Position Errors

Problem: Wrong positions showing for personnel groups Cause: System using default calculations instead of defined positions Solution: Edit personnel group and check correct position boxes

FIX CLAUDE: alias claude="npx @anthropic-ai/claude-code" claude --version