archery-bookkeeper/CLAUDE.md

archery bookkeeper - project documentation

A professional archery scoring application built with Flutter, designed to match traditional paper scorecards with modern digital convenience.

project overview

This Flutter application provides an intuitive scoring interface for archery practice and competition, featuring:

• Digital scorecard matching traditional paper layouts
• Real-time score calculation and running totals
• Configurable settings for different archery formats
• Color-coded scoring keypad for efficient input
• X/10/9 counting for precision tracking

The app follows clean architecture principles with a modular structure ready for scaling and advanced features.

current implementation status

✅ completed features

core UI components:

• ScoringPage: Main application interface with settings and layout management
• ScoringGrid: Complete responsive scorecard with static 12-row layout supporting both 3/6-arrow modes
• ScoringKeypad: 4x3 grid layout (X,10,9/8,7,6/5,4,3/2,1,M) plus CLEAR button with archery-standard color coding
• ScoringCell: Individual score input cells with selection highlighting and tap handling
• ToggleSwitches: Arrow count configuration (3/6 arrows per end) with automatic end inference

scoring logic:

• Dynamic calculation system with logical-to-visual end mapping
• Sum of 3 calculations: active in 3-arrow mode, greyed in 6-arrow mode
• Sum of 6 calculations: displays on odd visual rows in both modes
• Real-time accumulative running totals with proper bounds checking
• X/10/9 counting with dedicated counters
• CLEAR functionality for score correction and editing
• Auto-advance input progression through scorecard

visual design & architecture:

• Centralized color system with ScoringColorScheme class providing consistent theming
• Traditional and lowSaturation color schemes with explicit text/background color pairs
• Intelligent column greying: sum of 6 in 3-arrow mode, sum of 3 in 6-arrow mode
• Responsive percentage-based layout eliminating viewport overflow issues
• Clean merged header design with "Arrows" label replacing individual column indices
• Disabled state colors for conditional UI elements with seamless visual hierarchy
• Material 3 theme integration with archery-standard color conventions

technical improvements:

• Flutter lints upgraded to 6.0.0 for modern code quality standards
• Complete color architecture documentation in _constants.md
• Single source of truth for all score-related visual styling through ScoringColors class
• Performance-optimized compile-time color constants with no runtime overhead
• Static 12-row grid architecture replacing dynamic column spawning for stability
• Logical grouping system with proper visual-to-logical end mapping for accurate calculations

📋 architecture overview

lib/
├── config/              # Configuration and settings
│   ├── constants/       # App-wide constants and color systems
│   │   ├── scoring_colors.dart    # Centralized color scheme architecture
│   │   └── _constants.md         # Color system documentation
│   ├── localization/    # Multi-language support files
│   └── settings/        # User preferences and app config
├── core/                # Business logic and models
│   ├── calculators/     # Score calculation logic
│   ├── models/          # Data models (Arrow, End, Set, Match)
│   └── validators/      # Input validation logic
├── data/                # Data layer implementation
│   ├── database/        # SQLite database setup
│   ├── datasources/     # Local and remote data sources
│   ├── models/          # Data transfer objects
│   └── repositories/    # Data access layer
├── export/              # Score export functionality
├── presentation/        # UI layer
│   ├── controllers/     # State management controllers
│   ├── pages/          # Application screens
│   │   └── scoring_page.dart
│   └── widgets/        # Reusable UI components
│       ├── common/     # Shared widgets
│       │   └── toggle_switches.dart
│       └── scoring_grid/  # Scoring-specific widgets
│           ├── scoring_cell.dart
│           ├── scoring_grid.dart
│           └── scoring_keypad.dart
└── main.dart           # Application entry point

🎯 current functionality

score input system:

• Tap any cell in the scorecard to select it
• Use the keypad to input scores (X, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, M)
• Auto-advance moves to the next cell after score input
• CLEAR button removes score from selected cell

calculation engine:

• Real-time end totals with X=10, M=0 scoring and proper bounds checking
• Mode-specific behavior: 3-arrow (10 ends) vs 6-arrow (6 ends) automatically inferred
• Sum of 3: active per row in 3-arrow mode, completely greyed in 6-arrow mode
• Sum of 6: displays on odd visual rows in both modes with correct 6-arrow grouping
• Accumulative column shows running total through each logical end
• X/10/9 counters track precision shots
• Final score displayed prominently

configuration options:

• Toggle between 3 or 6 arrows per end
• End count automatically inferred: 3-arrow mode = 10 ends (Indoor), 6-arrow mode = 6 ends (Outdoor)
• Settings automatically reinitialize scorecard with proper logical grouping

adaptive color management:

• Centralized ScoringColorScheme architecture with traditional and lowSaturation variants
• Intelligent sum of 6 column greying in 3-arrow mode while preserving layout
• Disabled state colors maintaining visual hierarchy for inactive elements
• Explicit text/background color pairs ensuring optimal contrast across all schemes

next development priorities

🚧 immediate UI improvements (4 remaining)

keypad interaction enhancements:

• implement keypad pop-up behavior for better mobile UX
• prevent UI push-up when keypad appears on screen
• add auto-retract keypad functionality after score input
• include manual close button for keypad dismissal

scorecard polish:

• implement end grouping visual cues to highlight all cells of the currently selected end
• implement per-end descending sort for score organization

🔧 core architecture improvements

1. data models creation:

   • core/models/arrow.dart: Individual arrow score with value and metadata
   • core/models/end.dart: Collection of arrows with calculations
   • core/models/set.dart: Collection of ends with set-level statistics
   • core/models/match.dart: Complete scoring session with settings

2. score calculator refactoring:

   • Move calculation logic from widgets to core/calculators/score_calculator.dart
   • Implement proper business logic separation
   • Add validation for score inputs

3. state management implementation:

   • Choose Provider or Riverpod for application state
   • Create proper state management for scoring sessions
   • Implement reactive UI updates

4. data persistence layer:

   • SQLite integration for local storage
   • Scoring session save/load functionality
   • Historical data tracking

🚀 feature development roadmap

phase 1 - foundation:

• Local storage implementation with SQLite
• Session management (new, save, load)
• Settings persistence using SharedPreferences
• Score validation and error handling

phase 2 - user experience:

• Session history page with saved scoring sessions
• Export system for score card images
• Physical keyboard support for desktop platforms
• Improved visual polish and responsiveness

phase 3 - advanced features:

• Multi-language support with JSON localization files
• Different archery round types (FITA, NFAA, etc.)
• Cloud synchronization with Google Drive integration
• Social sharing capabilities (Twitter, image sharing)

phase 4 - competition features:

• Multi-archer scoring support
• Tournament management capabilities
• Performance statistics and progress tracking
• Advanced export options (PDF reports, CSV data)

📱 platform considerations

current support:

• Android (tested and working)
• iOS (Flutter cross-platform ready)
• Web (Flutter web enabled)
• Desktop (Windows, macOS, Linux support available)

responsive design:

• Portrait orientation optimized
• Landscape support needed for tablets
• Desktop keyboard navigation
• Accessibility improvements for screen readers

technical implementation notes

dependencies

Current pubspec.yaml includes essential dependencies:

• Flutter SDK ^3.9.0 with Material 3 theme support
• Cupertino icons ^1.0.8 for iOS consistency
• Flutter lints ^6.0.0 for modern code quality standards
• Dependency overrides ensuring compatibility with latest Flutter versions

Recommended additions for full implementation:

dependencies:
  # State management
  provider: ^6.0.5
  # or
  flutter_riverpod: ^2.4.6
  
  # Database
  sqflite: ^2.3.0
  path: ^1.8.3
  
  # Storage
  shared_preferences: ^2.2.2
  
  # Export functionality
  image: ^4.1.3
  pdf: ^3.10.6
  
  # Internationalization
  intl: ^0.19.0
  
  # Development
  json_annotation: ^4.8.1

dev_dependencies:
  # Code generation
  build_runner: ^2.4.7
  json_serializable: ^6.7.1

centralized color architecture

The application features a sophisticated color management system with the ScoringColorScheme class providing consistent visual theming across all components.

key architectural features:

• Complete color system in lib/config/constants/scoring_colors.dart
• Traditional (vibrant) and lowSaturation (muted) color schemes available
• Explicit text/background color pairs preventing contrast issues
• Comprehensive disabled state support for conditional UI elements
• Performance-optimized compile-time constants with zero runtime overhead

intelligent adaptive behavior:

• Sum of 6 column automatically greys out in 3-arrow mode while maintaining layout
• Disabled states preserve visual hierarchy while clearly indicating inactive status
• Color scheme switching requires single constant change for global application
• Extensible architecture ready for additional themes (high contrast, dark mode, etc.)

See lib/config/constants/_constants.md for complete usage documentation and implementation examples.

code organization principles

separation of concerns:

• Presentation layer handles only UI logic
• Business logic isolated in core modules
• Data access abstracted through repositories
• Configuration centralized in config modules

testability:

• Widget tests for UI components
• Unit tests for business logic
• Integration tests for complete workflows
• Mock implementations for external dependencies

maintainability:

• Clear naming conventions throughout
• Consistent file and directory organization
• Documentation for complex business rules
• Error handling at appropriate layers

design decisions and rationale

scorecard layout

The scoring grid exactly matches traditional paper scorecards to ensure familiar user experience:

• End numbers in left column for easy reference
• Arrow score columns (#1, #2, #3 or #1-#6)
• Calculated columns (Sum of 3, Sum of 6, Accumulative) match paper format
• X/10/9 counting section at bottom for quick reference

keypad design

Button layout follows the user's exact specifications:

• 4x3 grid with logical score arrangement
• Color coding matches archery scoring conventions
• CLEAR button prominently placed for error correction
• Touch-friendly sizing for mobile devices

auto-advance behavior

Score input automatically moves to the next logical cell:

• Within an end: moves from arrow #1 to #2 to #3
• Between ends: moves to arrow #1 of next end
• Reduces tap count and speeds up scoring process
• Can be overridden by tapping specific cells

calculation accuracy

All score calculations follow official archery rules:

• X scores as 10 points in totals
• M (miss) scores as 0 points
• Sum of 6 only displays on even-numbered ends
• Accumulative totals include all previous ends
• Final score matches bottom accumulative cell

file structure reference

key implementation files

main application:

• /lib/main.dart - Application entry point and Material app setup
• /lib/presentation/pages/scoring_page.dart - Main scoring interface with state management

scoring components:

• /lib/presentation/widgets/scoring_grid/scoring_grid.dart - Complete scorecard with calculations
• /lib/presentation/widgets/scoring_grid/scoring_cell.dart - Individual score input cells
• /lib/presentation/widgets/scoring_grid/scoring_keypad.dart - 4x3 score input keypad
• /lib/presentation/widgets/common/toggle_switches.dart - Configuration toggles

color architecture:

• /lib/config/constants/scoring_colors.dart - Centralized color scheme definitions
• /lib/config/constants/_constants.md - Complete color system documentation

design references:

• /.uidesign/scorecard.xlsx - Excel template with exact layout specifications
• /.uidesign/keypad_layout.xlsx - Keypad button colors and arrangement
• /.uidesign/scorecard.pdf - Visual reference for scorecard format

configuration:

• /pubspec.yaml - Flutter project configuration and dependencies
• /analysis_options.yaml - Dart analyzer rules and linting

development workflow

getting started

1. environment setup:

   flutter doctor
   flutter pub get
   

2. running the application:

   flutter run
   # or for specific platform
   flutter run -d chrome      # Web
   flutter run -d windows     # Windows desktop
   

3. testing:

   flutter test
   flutter test --coverage
   

adding new features

1. follow the modular architecture:

   • Business logic goes in core/
   • UI components in presentation/widgets/
   • Data handling in data/

2. maintain the design consistency:

   • Reference .uidesign/ files for visual specifications
   • Follow established color schemes and layouts
   • Test on multiple screen sizes

3. update tests:

   • Add unit tests for business logic
   • Create widget tests for new UI components
   • Include integration tests for complete workflows

conclusion

The archery bookkeeper application has evolved into a mature scoring interface with sophisticated visual architecture and polished user experience. The centralized color system, intelligent adaptive behavior, and optimized layouts create a professional-grade foundation that matches traditional paper scorecards while leveraging modern digital capabilities.

current strength highlights:

• Complete centralized color architecture with traditional and lowSaturation schemes
• Robust 6-arrow layout with static 12-row grid and logical-to-visual end mapping
• Responsive percentage-based layout eliminating viewport overflow issues
• Intelligent column greying maintaining layout consistency in both 3/6-arrow modes
• Modern development practices with flutter_lints 6.0.0 and performance-optimized constants
• Comprehensive documentation enabling easy maintenance and feature expansion

The remaining 4 UI improvements focus on keypad interaction polish and end grouping visual cues. With the major 6-arrow layout architecture now complete and stable, the foundation is ready for the next major development phase focusing on data persistence and state management to transform the application from a sophisticated calculator into a complete scoring and session management solution for archery practitioners.

The application successfully balances authenticity to archery scoring conventions with modern Flutter development practices, creating a clean, professional foundation ready for advanced features while maintaining code quality and visual consistency throughout.