# priyanshurav/libreludo architecture

> Architecture diagram of the GitHub repository priyanshurav/libreludo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/priyanshurav/libreludo
- Repository: https://github.com/priyanshurav/libreludo

## Overview

LibreLudo is a browser-based Ludo game for local human and bot opponents. The user journey runs from player setup into a match, where dice rolls and token moves update Redux game state; token movement includes path calculation, capture, and win handling. Saved progress is validated and restored from browser storage. The README documents responsive and offline play, but the sampled sources do not show the full route-to-game wiring or PWA implementation, so those links are marked unverified or omitted.

Main entry points: [`src/hooks/useMoveAndCaptureToken.ts`](https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useMoveAndCaptureToken.ts) (Move orchestration), [`src/pages/Play/components/Game/Game.tsx`](https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Game/Game.tsx) (Game interface), [`src/state/store.ts`](https://github.com/priyanshurav/libreludo/blob/main/src/state/store.ts) (Redux store), [`src/game/storage/retrieveState.ts`](https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/retrieveState.ts) (State retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Player experience"]
  node_setup["Player setup<br/>[PlayerSetup.tsx]"]
  node_home["Home page<br/>[HomePage.tsx]"]
  node_guide["How to play<br/>[HowToPlay.tsx]"]
  node_gamepage["Play page<br/>[Play.tsx]"]
end

subgraph group_gameplay["Match gameplay"]
  node_gameui["Game interface<br/>[Game.tsx]"]
  node_board["Board display<br/>[Board.tsx]"]
  node_diceui["Dice control<br/>[Dice.tsx]"]
  node_tokenui["Token display<br/>[Token.tsx]"]
  node_finish["Match results"]
  node_bot["Bot decisions"]
  node_turn["Turn and dice flow"]
  node_move["Move orchestration"]
  node_animation["Token animation"]
  node_motionregistry["Motion registry"]
end

subgraph group_rules["Game rules"]
  node_sequence["Move sequences"]
  node_tokenrules["Token rules<br/>[logic.ts]"]
  node_coordinates["Board paths<br/>[logic.ts]"]
  node_alignment["Token alignment<br/>[alignment.ts]"]
end

subgraph group_state["State and persistence"]
  node_store[("Redux store<br/>[store.ts]")]
  node_players["Player state<br/>[playersSlice.ts]"]
  node_dice["Dice state<br/>[diceSlice.ts]"]
  node_persistence["Save and restore<br/>[saveState.ts]"]
  node_restore["State retrieval<br/>[retrieveState.ts]"]
  node_validation["Save validation<br/>[validator.ts]"]
  node_storage[("Browser storage<br/>[storage.ts]")]
  node_schema["Save schema<br/>[schema.ts]"]
  node_cleanup["Game cleanup<br/>[useCleanup.ts]"]
end

node_player(("Local players"))

node_player -->|"opens"| node_home
node_player -->|"configures"| node_setup
node_setup -.->|"starts match"| node_gamepage
node_gamepage -.->|"renders"| node_gameui
node_gameui -.->|"renders"| node_board
node_gameui -.->|"renders"| node_diceui
node_gameui -.->|"renders"| node_tokenui
node_gameui -.->|"shows results"| node_finish
node_player -->|"reads rules"| node_guide
node_turn -->|"invokes"| node_move
node_move -->|"calculates move"| node_sequence
node_move -->|"checks steps"| node_tokenrules
node_move -->|"runs capture"| node_animation
node_animation -->|"animates tokens"| node_motionregistry
node_animation -->|"resets alignment"| node_alignment
node_alignment -->|"compares coordinates"| node_coordinates
node_tokenrules -->|"uses path logic"| node_coordinates
node_turn -->|"selects bot move"| node_bot
node_move -->|"reads state"| node_store
node_move -->|"dispatches updates"| node_players
node_store -->|"combines reducer"| node_players
node_store -->|"combines reducer"| node_dice
node_move -->|"saves next state"| node_persistence
node_persistence -->|"writes save"| node_storage
node_persistence -->|"shapes save"| node_schema
node_restore -->|"reads save"| node_storage
node_restore -->|"validates state"| node_validation
node_restore -->|"hydrates state"| node_store
node_validation -->|"checks schema"| node_schema
node_cleanup -->|"clears state"| node_players
node_cleanup -->|"clears motion"| node_motionregistry

click node_setup "https://github.com/priyanshurav/libreludo/blob/main/src/pages/PlayerSetup/PlayerSetup.tsx"
click node_home "https://github.com/priyanshurav/libreludo/blob/main/src/pages/HomePage/HomePage.tsx"
click node_guide "https://github.com/priyanshurav/libreludo/blob/main/src/pages/HowToPlay/HowToPlay.tsx"
click node_gamepage "https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/Play.tsx"
click node_gameui "https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Game/Game.tsx"
click node_board "https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Board/Board.tsx"
click node_diceui "https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Dice/Dice.tsx"
click node_tokenui "https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Token/Token.tsx"
click node_finish "https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/GameFinishedScreen/GameFinishedScreen.tsx"
click node_bot "https://github.com/priyanshurav/libreludo/blob/main/src/game/bot/selectBestTokenForBot.ts"
click node_turn "https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useHandlePostDiceRoll.ts"
click node_move "https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useMoveAndCaptureToken.ts"
click node_animation "https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useCaptureTokenInSameCoord.ts"
click node_sequence "https://github.com/priyanshurav/libreludo/blob/main/src/game/movement/calculateSequence.ts"
click node_tokenrules "https://github.com/priyanshurav/libreludo/blob/main/src/game/tokens/logic.ts"
click node_coordinates "https://github.com/priyanshurav/libreludo/blob/main/src/game/coords/logic.ts"
click node_alignment "https://github.com/priyanshurav/libreludo/blob/main/src/game/tokens/alignment.ts"
click node_store "https://github.com/priyanshurav/libreludo/blob/main/src/state/store.ts"
click node_players "https://github.com/priyanshurav/libreludo/blob/main/src/state/slices/playersSlice.ts"
click node_dice "https://github.com/priyanshurav/libreludo/blob/main/src/state/slices/diceSlice.ts"
click node_persistence "https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/saveState.ts"
click node_restore "https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/retrieveState.ts"
click node_validation "https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/validator.ts"
click node_storage "https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/storage.ts"
click node_schema "https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/schema.ts"
click node_motionregistry "https://github.com/priyanshurav/libreludo/blob/main/src/game/movement/tokenMotionRegistry.ts"
click node_cleanup "https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useCleanup.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup,node_home,node_guide,node_gamepage toneBlue
class node_gameui,node_board,node_diceui,node_tokenui,node_finish,node_bot,node_turn,node_move,node_animation,node_motionregistry toneAmber
class node_sequence,node_tokenrules,node_coordinates,node_alignment toneMint
class node_store,node_players,node_dice,node_persistence,node_restore,node_validation,node_storage,node_schema,node_cleanup toneRose
class node_player toneIndigo
```

## Components

### Player experience

- [Player setup](https://github.com/priyanshurav/libreludo/blob/main/src/pages/PlayerSetup/PlayerSetup.tsx): `src/pages/PlayerSetup/PlayerSetup.tsx`
- [Home page](https://github.com/priyanshurav/libreludo/blob/main/src/pages/HomePage/HomePage.tsx): `src/pages/HomePage/HomePage.tsx`
- [How to play](https://github.com/priyanshurav/libreludo/blob/main/src/pages/HowToPlay/HowToPlay.tsx): `src/pages/HowToPlay/HowToPlay.tsx`
- [Play page](https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/Play.tsx): `src/pages/Play/Play.tsx`

### Match gameplay

- [Game interface](https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Game/Game.tsx): `src/pages/Play/components/Game/Game.tsx`
- [Board display](https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Board/Board.tsx): `src/pages/Play/components/Board/Board.tsx`
- [Dice control](https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Dice/Dice.tsx): `src/pages/Play/components/Dice/Dice.tsx`
- [Token display](https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/Token/Token.tsx): `src/pages/Play/components/Token/Token.tsx`
- [Match results](https://github.com/priyanshurav/libreludo/blob/main/src/pages/Play/components/GameFinishedScreen/GameFinishedScreen.tsx): `src/pages/Play/components/GameFinishedScreen/GameFinishedScreen.tsx`
- [Bot decisions](https://github.com/priyanshurav/libreludo/blob/main/src/game/bot/selectBestTokenForBot.ts): `src/game/bot/selectBestTokenForBot.ts`
- [Turn and dice flow](https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useHandlePostDiceRoll.ts): `src/hooks/useHandlePostDiceRoll.ts`
- [Move orchestration](https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useMoveAndCaptureToken.ts): `src/hooks/useMoveAndCaptureToken.ts`
- [Token animation](https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useCaptureTokenInSameCoord.ts): `src/hooks/useCaptureTokenInSameCoord.ts`
- [Motion registry](https://github.com/priyanshurav/libreludo/blob/main/src/game/movement/tokenMotionRegistry.ts): `src/game/movement/tokenMotionRegistry.ts`

### Game rules

- [Move sequences](https://github.com/priyanshurav/libreludo/blob/main/src/game/movement/calculateSequence.ts): `src/game/movement/calculateSequence.ts`
- [Token rules](https://github.com/priyanshurav/libreludo/blob/main/src/game/tokens/logic.ts): `src/game/tokens/logic.ts`
- [Board paths](https://github.com/priyanshurav/libreludo/blob/main/src/game/coords/logic.ts): `src/game/coords/logic.ts`
- [Token alignment](https://github.com/priyanshurav/libreludo/blob/main/src/game/tokens/alignment.ts): `src/game/tokens/alignment.ts`

### State and persistence

- [Redux store](https://github.com/priyanshurav/libreludo/blob/main/src/state/store.ts): `src/state/store.ts`
- [Player state](https://github.com/priyanshurav/libreludo/blob/main/src/state/slices/playersSlice.ts): `src/state/slices/playersSlice.ts`
- [Dice state](https://github.com/priyanshurav/libreludo/blob/main/src/state/slices/diceSlice.ts): `src/state/slices/diceSlice.ts`
- [Save and restore](https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/saveState.ts): `src/game/storage/saveState.ts`
- [State retrieval](https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/retrieveState.ts): `src/game/storage/retrieveState.ts`
- [Save validation](https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/validator.ts): `src/game/storage/validator.ts`
- [Browser storage](https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/storage.ts): `src/game/storage/storage.ts`
- [Save schema](https://github.com/priyanshurav/libreludo/blob/main/src/game/storage/schema.ts): `src/game/storage/schema.ts`
- [Game cleanup](https://github.com/priyanshurav/libreludo/blob/main/src/hooks/useCleanup.ts): `src/hooks/useCleanup.ts`

### Other components

- **Local players**

## Connections

- Local players → Home page: opens (evidence: `README.md`)
- Local players → Player setup: configures (evidence: `README.md`)
- Player setup → Play page: starts match
- Play page → Game interface: renders
- Game interface → Board display: renders
- Game interface → Dice control: renders
- Game interface → Token display: renders
- Game interface → Match results: shows results
- Local players → How to play: reads rules (evidence: `README.md`)
- Turn and dice flow → Move orchestration: invokes (evidence: `src/hooks/useHandlePostDiceRoll.ts`)
- Move orchestration → Move sequences: calculates move (evidence: `src/hooks/useMoveAndCaptureToken.ts`)
- Move orchestration → Token rules: checks steps (evidence: `src/hooks/useMoveAndCaptureToken.ts`)
- Move orchestration → Token animation: runs capture (evidence: `src/hooks/useMoveAndCaptureToken.ts`)
- Token animation → Motion registry: animates tokens (evidence: `src/hooks/useCaptureTokenInSameCoord.ts`)
- Token animation → Token alignment: resets alignment (evidence: `src/hooks/useCaptureTokenInSameCoord.ts`)
- Token alignment → Board paths: compares coordinates (evidence: `src/game/tokens/alignment.ts`)
- Token rules → Board paths: uses path logic (evidence: `src/game/tokens/logic.ts`)
- Turn and dice flow → Bot decisions: selects bot move
- Move orchestration → Redux store: reads state (evidence: `src/hooks/useMoveAndCaptureToken.ts`)
- Move orchestration → Player state: dispatches updates (evidence: `src/hooks/useMoveAndCaptureToken.ts`)
- Redux store → Player state: combines reducer (evidence: `src/state/store.ts`)
- Redux store → Dice state: combines reducer (evidence: `src/state/store.ts`)
- Move orchestration → Save and restore: saves next state (evidence: `src/hooks/useMoveAndCaptureToken.ts`)
- Save and restore → Browser storage: writes save (evidence: `src/game/storage/saveState.ts`)
- Save and restore → Save schema: shapes save (evidence: `src/game/storage/saveState.ts`)
- State retrieval → Browser storage: reads save (evidence: `src/game/storage/retrieveState.ts`)
- State retrieval → Save validation: validates state (evidence: `src/game/storage/retrieveState.ts`)
- State retrieval → Redux store: hydrates state (evidence: `src/game/storage/retrieveState.ts`)
- Save validation → Save schema: checks schema (evidence: `src/game/storage/validator.ts`)
- Game cleanup → Player state: clears state (evidence: `src/hooks/useCleanup.ts`)
- Game cleanup → Motion registry: clears motion (evidence: `src/hooks/useCleanup.ts`)
