# 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: ```yaml 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**: ```bash flutter doctor flutter pub get ``` 2. **running the application**: ```bash flutter run # or for specific platform flutter run -d chrome # Web flutter run -d windows # Windows desktop ``` 3. **testing**: ```bash 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.