BSC Score - Pool Scoring Application

A modern, responsive pool/billiards scoring application built with Astro and Preact, following best practices for maintainability, performance, and reusability.

✨ Features

• Multi-game Support: 8-Ball, 9-Ball, 10-Ball, and 14/1 Endlos
• Real-time Scoring: Live score tracking with undo functionality
• Player Management: Automatic player name history and suggestions
• Game Management: Create, track, and manage multiple games
• Responsive Design: Optimized for mobile and desktop
• Progressive Web App: Offline support and app-like experience
• TypeScript: Full type safety for better development experience

🏗️ Architecture

This project has been refactored following modern software development best practices:

Separation of Concerns

• Services Layer: Game data management and localStorage operations
• Custom Hooks: Reusable state management logic
• Components: UI components with single responsibilities
• Utils: Pure utility functions for common operations

Type Safety

• Full TypeScript implementation
• Comprehensive type definitions for game domain
• Type-safe component props and state management

Component Architecture

src/
├── components/
│   ├── ui/           # Reusable UI components (Button, Card, Layout)
│   ├── screens/      # Screen-level components
│   └── ...           # Feature-specific components
├── hooks/            # Custom React/Preact hooks
├── services/         # Business logic and data management
├── types/            # TypeScript type definitions
├── utils/            # Pure utility functions
└── styles/           # Global styles and CSS modules

State Management

• useGameState: Centralized game data management
• useNavigation: Screen and routing state
• useModal: Modal state management
• Custom hooks: Encapsulated, reusable state logic

Design System

• Consistent design tokens and CSS custom properties
• Reusable UI components with variant support
• Responsive design patterns
• Accessibility-first approach

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Clone the repository
git clone <repository-url>
cd bscscore

# Install dependencies
npm install

# Start development server
npm run dev

Available Scripts

npm run dev      # Start development server
npm run build    # Build for production
npm run preview  # Preview production build
npm run test:record  # Record browser interactions with Playwright
npm run test:e2e    # Run all recorded browser automation scripts

Building with Docker

# Build for production using Docker
docker run -it -v $(pwd):/app -w /app --rm node:latest npx astro build

🧪 Testing

The project uses Playwright for browser automation and recording. This allows you to record interactions once and replay them anytime, making it easy to test repetitive workflows.

Quick Start

Recording interactions:

# Terminal 1: Start dev server
npm run dev

# Terminal 2: Start recording
npm run test:record

Running recordings:

npm run test:e2e

Features

• Record interactions: Use Playwright codegen to capture clicks, form fills, and navigation
• Replay scripts: Run recorded scripts automatically
• Duplicate & modify: Copy any script and modify it (e.g., change the last step from clicking 'z' to clicking 'a')
• Full scripting power: Edit generated TypeScript files directly for custom automation

Documentation

For detailed instructions on recording, modifying, and running scripts, see:

• tests/recordings/README.md - Complete workflow documentation

📁 Project Structure

Core Components

• App.tsx - Main application component with orchestrated state management
• screens/ - Screen-level components (GameList, NewGame, GameDetail)
• ui/ - Reusable UI components following design system

State Management

• hooks/useGameState.ts - Game CRUD operations and persistence
• hooks/useNavigation.ts - Application routing and screen state
• hooks/useModal.ts - Modal state management

Business Logic

• services/gameService.ts - Game creation, updates, and business rules
• utils/gameUtils.ts - Game-related utility functions
• utils/validation.ts - Input validation and sanitization

Type Definitions

• types/game.ts - Game domain types
• types/ui.ts - UI component types
• types/css-modules.d.ts - CSS modules type support

🎯 Key Improvements

From Monolithic to Modular

• Before: 360-line App component handling everything
• After: Separated concerns with focused, single-responsibility components

Type Safety

• Before: JavaScript with PropTypes comments
• After: Full TypeScript with comprehensive type definitions

State Management

• Before: All state in one component with prop drilling
• After: Custom hooks with proper encapsulation and reusability

Reusability

• Before: Tightly coupled, single-use components
• After: Reusable UI components with variant support

Performance

• Before: Client-side only rendering
• After: Astro's islands architecture with optimal hydration

Developer Experience

• Before: No structure, mixed concerns
• After: Clear architecture, proper tooling, and documentation

🛠️ Technology Stack

• Framework: Astro - Islands architecture for optimal performance
• UI Library: Preact - Lightweight React alternative
• Language: TypeScript - Type safety and better DX
• Styling: CSS Modules with design tokens
• Build Tool: Vite (integrated with Astro)

📱 Progressive Web App

The application includes PWA features:

• Offline support with service worker
• App manifest for "Add to Home Screen"
• Optimized for mobile devices
• Fast loading with proper caching strategies

🎨 Design System

Design Tokens

• Consistent color palette
• Standardized spacing and sizing
• Responsive breakpoints
• Accessibility-compliant contrast ratios

Component Variants

• Button: primary, secondary, danger
• Card: default, elevated, outlined
• Sizes: small, medium, large

🧪 Best Practices Implemented

Code Quality

• ✅ SOLID principles
• ✅ DRY (Don't Repeat Yourself)
• ✅ Single Responsibility Principle
• ✅ Proper separation of concerns
• ✅ TypeScript strict mode

Performance

• ✅ Code splitting with Astro islands
• ✅ Optimized bundle size
• ✅ Efficient re-rendering with proper hooks
• ✅ CSS Modules for optimized styling

Accessibility

• ✅ ARIA labels and roles
• ✅ Keyboard navigation support
• ✅ Screen reader compatibility
• ✅ High contrast support

Maintainability

• ✅ Clear file structure
• ✅ Comprehensive documentation
• ✅ Type safety throughout
• ✅ Modular, testable components

🔧 Configuration

Astro Configuration

• Preact integration with React compatibility
• TypeScript strict mode
• Optimized build settings
• Development server configuration

TypeScript Configuration

• Strict type checking
• Modern ES2020+ features
• CSS Modules support
• Astro-specific types

📈 Future Improvements

• Unit and integration testing (if needed)
• Internationalization (i18n) support
• Advanced game statistics and analytics
• Real-time multiplayer support
• Game export/import functionality

🤝 Contributing

This codebase follows strict development principles:

1. Every feature must be type-safe
2. Components must be reusable and well-documented
3. Business logic must be separated from UI logic
4. All changes must follow the established architecture patterns

📄 License

[Include your license information here]