# BSC Score Modular Architecture

This document captures the reusable module layout introduced in the refactor.  
Everything under `src/lib` is now consumable from other React/Preact hosts without depending on the Astro shell that ships in this repository.

## Module Overview

- `@lib/domain` – **Pure domain logic** (types, constants, validation helpers, formatters).  
  No framework dependencies, no browser APIs. Safe to re-use from Node or tests.
- `@lib/data` – **Persistence services** (IndexedDB access, repository abstractions, test harness).  
  Wraps browser APIs and isolates side-effects away from UI/state.
- `@lib/state` – **Composable hooks** that orchestrate domain + data layers.  
  Exported hooks expose serialisable state and imperative actions.
- `@lib/ui` – **Stateless presentational primitives** (buttons, cards, layout shell, generic modals).  
  Ship with co-located CSS modules and type-safe props.
- `@lib/features/*` – **Feature bundles** that compose UI + state to deliver end-user flows.  
  Current bundles:
  - `game-list` (list + filter experience)
  - `game-detail` (scoreboard with break tracking)
  - `game-lifecycle` (completion modal + rematch workflow)
  - `new-game` (wizard steps and player pickers)

## Import Surfaces

All entry points are re-exported via `@lib/index.ts`, so consumers can either:

```ts
import { GameService, useGameState, GameList } from '@lib';
```

or pick a scoped module:

```ts
import { GameService } from '@lib/data';
import { GameList } from '@lib/features/game-list';
```

## Cross-Cutting Rules

- **Domain first**: New feature logic should be expressed with domain types and helpers before touching hooks/UI.
- **One-way dependencies**:
  ```
  domain → data → state → features → app shell
  ```
  Lower layers must not import from higher ones.
- **CSS modules stay co-located** with the component they style. Consumers receive the compiled class names via the exported component props.
- **Documentation lives next to code**: every module has a `README.md` describing intent, public API, and integration notes.

## Migration Notes

- Legacy `src/components` now only hosts the Astro shell (`App.tsx`, `BscScoreApp.astro`, etc.).  
  All reusable React pieces were migrated under `src/lib`.
- Path aliases:
  - `@/*` → `src/*`
  - `@lib/*` → `src/lib/*`
  Update your editor/tsconfig if you embed these modules elsewhere.
- Tests should import from `@lib` to avoid depending on Astro-specific wiring.

## Next Steps

- Promote more feature-level Storybook / Playwright fixtures into `src/lib/docs`.
- When adding new modules, extend `src/lib/index.ts` and document usage in the corresponding folder.