bscscore/README.md

# 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
```bash
# Clone the repository
git clone <repository-url>
cd bscscore

# Install dependencies
npm install

# Start development server
npm run dev
```

### Available Scripts
```bash
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
```bash
# 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:**
```bash
# Terminal 1: Start dev server
npm run dev

# Terminal 2: Start recording
npm run test:record
```

**Running recordings:**
```bash
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](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](https://astro.build/) - Islands architecture for optimal performance
- **UI Library**: [Preact](https://preactjs.com/) - Lightweight React alternative
- **Language**: [TypeScript](https://www.typescriptlang.org/) - 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]