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

📁 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 with Vitest
• E2E testing with Playwright
• 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]