# hkoado/ootv2-game architecture

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

- Interactive diagram: https://gitdiagram.com/hkoado/ootv2-game
- Repository: https://github.com/hkoado/ootv2-game

## Overview

OTTv2 is a browser-based 9×9 strategy game for two seated players, with spectators following rooms in real time. The principal flow is: players create or join a room, the host approves the opponent, each team places its pieces in timed setup, then players take turns moving and capturing until a win condition is met; the interface shows the board, player counts, history and result. The README describes real-time room sync and spectator support; source excerpts show game rules and state handling, but do not expose every sync transport detail.

Main entry points: [`src/App.jsx`](https://github.com/hkoado/ootv2-game/blob/Ex2/src/App.jsx) (App coordinator), [`src/sync/usePlayRoom.js`](https://github.com/hkoado/ootv2-game/blob/Ex2/src/sync/usePlayRoom.js) (Room state hook), [`src/components/Board.jsx`](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Board.jsx) (Interactive board), [`src/game/rules.js`](https://github.com/hkoado/ootv2-game/blob/Ex2/src/game/rules.js) (Move and win rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Player experience"]
  node_app["App coordinator<br/>[App.jsx]"]
  node_lobby["Lobby<br/>[Lobby.jsx]"]
  node_header["Room header<br/>[Header.jsx]"]
  node_gameover["Game result<br/>[GameOverModal.jsx]"]
  node_rulesmodal["Rules guide<br/>[RulesModal.jsx]"]
end

subgraph group_room["Rooms and sync"]
  node_roomhook["Room state hook<br/>[usePlayRoom.js]"]
  node_playhtml["playhtml sync"]
  node_partykit["PartyKit service"]
  node_peer["PeerJS connections"]
  node_broadcast["BroadcastChannel fallback"]
end

subgraph group_gameplay["Game stages"]
  node_board["Interactive board<br/>[Board.jsx]"]
  node_square["Board squares<br/>[Square.jsx]"]
  node_piece["Piece display<br/>[Piece.jsx]"]
  node_setup["Timed setup<br/>[SetupPanel.jsx]"]
  node_playercard["Player status<br/>[PlayerCard.jsx]"]
  node_history["Move history<br/>[MoveHistory.jsx]"]
  node_icons["Piece icons<br/>[PieceIcons.jsx]"]
end

subgraph group_engine["Game engine"]
  node_state["Game state machine<br/>[gameState.js]"]
  node_rules["Move and win rules<br/>[rules.js]"]
  node_constants["Board and piece constants<br/>[constants.js]"]
end

node_players(("Players and spectators"))

node_players -->|"create or join"| node_lobby
node_lobby -->|"requests room"| node_app
node_app -->|"coordinates room"| node_roomhook
node_roomhook -->|"syncs state"| node_playhtml
node_playhtml -->|"uses infrastructure"| node_partykit
node_roomhook -.->|"connects peers"| node_peer
node_roomhook -.->|"falls back"| node_broadcast
node_roomhook -->|"creates and updates"| node_state
node_state -->|"validates moves and wins"| node_rules
node_rules -->|"reads rules data"| node_constants
node_state -->|"reads game definitions"| node_constants
node_app -->|"renders"| node_lobby
node_app -->|"renders"| node_header
node_app -->|"renders and handles actions"| node_board
node_app -->|"renders and handles setup"| node_setup
node_app -->|"renders"| node_playercard
node_app -->|"renders"| node_history
node_app -->|"shows result"| node_gameover
node_header -->|"opens rules"| node_rulesmodal
node_board -->|"gets valid moves"| node_rules
node_board -->|"renders squares"| node_square
node_board -->|"renders pieces"| node_piece
node_setup -->|"renders piece icons"| node_icons
node_playercard -->|"counts remaining pieces"| node_rules
node_players -->|"selects and moves"| node_board
node_players -->|"places pieces"| node_setup

click node_app "https://github.com/hkoado/ootv2-game/blob/Ex2/src/App.jsx"
click node_lobby "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Lobby.jsx"
click node_header "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Header.jsx"
click node_board "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Board.jsx"
click node_square "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Square.jsx"
click node_piece "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Piece.jsx"
click node_setup "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/SetupPanel.jsx"
click node_playercard "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/PlayerCard.jsx"
click node_history "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/MoveHistory.jsx"
click node_gameover "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/GameOverModal.jsx"
click node_rulesmodal "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/RulesModal.jsx"
click node_roomhook "https://github.com/hkoado/ootv2-game/blob/Ex2/src/sync/usePlayRoom.js"
click node_state "https://github.com/hkoado/ootv2-game/blob/Ex2/src/game/gameState.js"
click node_rules "https://github.com/hkoado/ootv2-game/blob/Ex2/src/game/rules.js"
click node_constants "https://github.com/hkoado/ootv2-game/blob/Ex2/src/game/constants.js"
click node_icons "https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/PieceIcons.jsx"

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_app,node_lobby,node_header,node_gameover,node_rulesmodal toneBlue
class node_roomhook,node_playhtml,node_partykit,node_peer,node_broadcast toneAmber
class node_board,node_square,node_piece,node_setup,node_playercard,node_history,node_icons toneMint
class node_state,node_rules,node_constants toneRose
class node_players toneIndigo
```

## Components

### Player experience

- [App coordinator](https://github.com/hkoado/ootv2-game/blob/Ex2/src/App.jsx): `src/App.jsx`
- [Lobby](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Lobby.jsx): `src/components/Lobby.jsx`
- [Room header](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Header.jsx): `src/components/Header.jsx`
- [Game result](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/GameOverModal.jsx): `src/components/GameOverModal.jsx`
- [Rules guide](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/RulesModal.jsx): `src/components/RulesModal.jsx`

### Rooms and sync

- [Room state hook](https://github.com/hkoado/ootv2-game/blob/Ex2/src/sync/usePlayRoom.js): `src/sync/usePlayRoom.js`
- **playhtml sync**
- **PartyKit service**
- **PeerJS connections**
- **BroadcastChannel fallback**

### Game stages

- [Interactive board](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Board.jsx): `src/components/Board.jsx`
- [Board squares](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Square.jsx): `src/components/Square.jsx`
- [Piece display](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/Piece.jsx): `src/components/Piece.jsx`
- [Timed setup](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/SetupPanel.jsx): `src/components/SetupPanel.jsx`
- [Player status](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/PlayerCard.jsx): `src/components/PlayerCard.jsx`
- [Move history](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/MoveHistory.jsx): `src/components/MoveHistory.jsx`
- [Piece icons](https://github.com/hkoado/ootv2-game/blob/Ex2/src/components/PieceIcons.jsx): `src/components/PieceIcons.jsx`

### Game engine

- [Game state machine](https://github.com/hkoado/ootv2-game/blob/Ex2/src/game/gameState.js): `src/game/gameState.js`
- [Move and win rules](https://github.com/hkoado/ootv2-game/blob/Ex2/src/game/rules.js): `src/game/rules.js`
- [Board and piece constants](https://github.com/hkoado/ootv2-game/blob/Ex2/src/game/constants.js): `src/game/constants.js`

### Other components

- **Players and spectators**

## Connections

- Players and spectators → Lobby: create or join
- Lobby → App coordinator: requests room
- App coordinator → Room state hook: coordinates room
- Room state hook → playhtml sync: syncs state
- playhtml sync → PartyKit service: uses infrastructure
- Room state hook → PeerJS connections: connects peers
- Room state hook → BroadcastChannel fallback: falls back
- Room state hook → Game state machine: creates and updates
- Game state machine → Move and win rules: validates moves and wins
- Move and win rules → Board and piece constants: reads rules data
- Game state machine → Board and piece constants: reads game definitions
- App coordinator → Lobby: renders
- App coordinator → Room header: renders
- App coordinator → Interactive board: renders and handles actions
- App coordinator → Timed setup: renders and handles setup
- App coordinator → Player status: renders
- App coordinator → Move history: renders
- App coordinator → Game result: shows result
- Room header → Rules guide: opens rules
- Interactive board → Move and win rules: gets valid moves
- Interactive board → Board squares: renders squares
- Interactive board → Piece display: renders pieces
- Timed setup → Piece icons: renders piece icons
- Player status → Move and win rules: counts remaining pieces
- Players and spectators → Interactive board: selects and moves
- Players and spectators → Timed setup: places pieces