bscscore/src/lib/docs/architecture.md

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:

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

or pick a scoped module:

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.