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

Everything reusable now lives under `src/lib`, allowing you to embed the core experience inside another React/Preact host without the Astro shell.

- **`@lib/domain`** – Pure TypeScript domain model (types, constants, validation, helpers).
- **`@lib/data`** – Persistence adapters and repositories (IndexedDB, migrations).
- **`@lib/state`** – Composable hooks that orchestrate domain + data.
- **`@lib/ui`** – Stateless UI primitives with co-located CSS modules.
- **`@lib/features/*`** – Feature bundles composing UI + state (game list, detail, lifecycle modals, new-game wizard).

The Astro `src/components` folder is now a thin host layer (screens + island bootstrap) that consumes the library.

Detailed module docs live in `src/lib/docs/architecture.md` and the individual `README.md` files under each package.

## 🚀 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**
- `src/components/App.tsx` - Astro-bound shell orchestrating library modules
- `src/components/screens/` - Screen containers consuming `@lib/features`
- `src/lib/` - Reusable application spine (domain/data/state/ui/features)

### **State Management**
- `@lib/state/useGameState` - Game CRUD operations and persistence
- `@lib/state/useNavigation` - Application routing and screen state
- `@lib/state/useModal` - Modal state management helpers

### **Business Logic**
- `@lib/data/gameService` - Game creation, updates, and persistence orchestration
- `@lib/domain/gameUtils` - Game-related utility functions
- `@lib/domain/validation` - Input validation and sanitisation

### **Type Definitions**
- `@lib/domain/types` - Game domain types
- `@lib/ui/types` - 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]