# elias-mujally/gridbreak architecture

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

- Interactive diagram: https://gitdiagram.com/elias-mujally/gridbreak
- Repository: https://github.com/elias-mujally/gridbreak

## Overview

GridBreak is a browser-based path-racing strategy game. Players choose a mode, map, layout, and controller, then play a Classic, Rush, or Convergence match locally against AI or other local players, or join an online room. The UI delegates rules and state transitions to shared game modules; online play adds protocol validation, a browser transport client, and a Cloudflare Worker/Durable Object room authority. The graph preserves documented online privacy and rematch capabilities; unsampled modules are included only where the README or source index supports their role.

Main entry points: [`src/game/engine.ts`](https://github.com/elias-mujally/gridbreak/blob/main/src/game/engine.ts) (Action engine), [`src/ui/App.tsx`](https://github.com/elias-mujally/gridbreak/blob/main/src/ui/App.tsx) (Local match UI), [`worker/index.ts`](https://github.com/elias-mujally/gridbreak/blob/main/worker/index.ts) (Worker admission and transport), [`src/online/room.ts`](https://github.com/elias-mujally/gridbreak/blob/main/src/online/room.ts) (Authoritative room)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Game experience"]
  node_app["Local match UI<br/>[App.tsx]"]
  node_setup["Mode and setup picker<br/>[ModePicker.tsx]"]
  node_convergence_ui["Convergence board"]
  node_online_ui["Online match UI<br/>[OnlineApp.tsx]"]
  node_online_race_ui["Online race board"]
end

subgraph group_rules["Shared game rules"]
  node_configuration["Modes and map capabilities<br/>[modes.ts]"]
  node_state["Match state and setup<br/>[state.ts]"]
  node_engine["Action engine<br/>[engine.ts]"]
  node_movement["Movement rules<br/>[movement.ts]"]
  node_walls["Wall legality<br/>[walls.ts]"]
  node_pathfinding["Route search<br/>[pathfinding.ts]"]
  node_rush["Rush actions and rewards<br/>[rush.ts]"]
  node_tiles["Rush tiles<br/>[tiles.ts]"]
  node_views["Player-specific views<br/>[view.ts]"]
  node_ai["AI controller<br/>[ai.ts]"]
  node_ai_rush["Rush AI strategy<br/>[aiRush.ts]"]
  node_ai_convergence["Convergence AI<br/>[aiConvergence.ts]"]
end

subgraph group_online["Online play"]
  node_online_client["Browser room client<br/>[client.ts]"]
  node_protocol["Online protocol<br/>[protocol.ts]"]
  node_identity["Guest identity<br/>[identity.ts]"]
end

subgraph group_server["Room service"]
  node_worker["Worker admission and transport<br/>[index.ts]"]
  node_room["Authoritative room<br/>[room.ts]"]
  node_durable_storage[("Durable Object storage")]
end

node_player(("Player"))

node_player -->|"chooses match"| node_setup
node_setup -->|"starts local match"| node_app
node_setup -->|"checks capabilities"| node_configuration
node_app -->|"applies actions"| node_engine
node_app -->|"requests AI action"| node_ai
node_app -->|"renders Convergence"| node_convergence_ui
node_app -->|"opens online play"| node_online_ui
node_convergence_ui -->|"applies local action"| node_engine
node_state -->|"builds configured match"| node_configuration
node_state -->|"generates Rush tiles"| node_tiles
node_engine -->|"checks legal moves"| node_movement
node_engine -->|"checks wall legality"| node_walls
node_engine -->|"dispatches Rush actions"| node_rush
node_movement -->|"checks steps"| node_walls
node_walls -->|"preserves routes"| node_pathfinding
node_pathfinding -->|"checks traversable edges"| node_walls
node_ai -->|"delegates Rush strategy"| node_ai_rush
node_ai -->|"delegates Convergence strategy"| node_ai_convergence
node_ai_rush -->|"evaluates player view"| node_views
node_ai_convergence -->|"scores routes"| node_pathfinding
node_online_ui -->|"uses room client"| node_online_client
node_online_ui -->|"renders race match"| node_online_race_ui
node_online_race_ui -->|"derives movement board"| node_views
node_online_client -->|"encodes room messages"| node_protocol
node_player -->|"joins online room"| node_online_ui
node_online_client -->|"connects by WebSocket"| node_worker
node_worker -->|"creates guest identity"| node_identity
node_worker -->|"validates messages"| node_protocol
node_worker -->|"dispatches room actions"| node_room
node_room -->|"executes authoritative actions"| node_engine
node_room -->|"projects player views"| node_views
node_room -->|"persists room state"| node_durable_storage

click node_app "https://github.com/elias-mujally/gridbreak/blob/main/src/ui/App.tsx"
click node_setup "https://github.com/elias-mujally/gridbreak/blob/main/src/ui/ModePicker.tsx"
click node_convergence_ui "https://github.com/elias-mujally/gridbreak/blob/main/src/ui/ConvergenceMatch.tsx"
click node_online_ui "https://github.com/elias-mujally/gridbreak/blob/main/src/ui/OnlineApp.tsx"
click node_online_race_ui "https://github.com/elias-mujally/gridbreak/blob/main/src/ui/OnlineRaceMatch.tsx"
click node_configuration "https://github.com/elias-mujally/gridbreak/blob/main/src/game/modes.ts"
click node_state "https://github.com/elias-mujally/gridbreak/blob/main/src/game/state.ts"
click node_engine "https://github.com/elias-mujally/gridbreak/blob/main/src/game/engine.ts"
click node_movement "https://github.com/elias-mujally/gridbreak/blob/main/src/game/movement.ts"
click node_walls "https://github.com/elias-mujally/gridbreak/blob/main/src/game/walls.ts"
click node_pathfinding "https://github.com/elias-mujally/gridbreak/blob/main/src/game/pathfinding.ts"
click node_rush "https://github.com/elias-mujally/gridbreak/blob/main/src/game/rush.ts"
click node_tiles "https://github.com/elias-mujally/gridbreak/blob/main/src/game/tiles.ts"
click node_views "https://github.com/elias-mujally/gridbreak/blob/main/src/game/view.ts"
click node_ai "https://github.com/elias-mujally/gridbreak/blob/main/src/game/ai.ts"
click node_ai_rush "https://github.com/elias-mujally/gridbreak/blob/main/src/game/aiRush.ts"
click node_ai_convergence "https://github.com/elias-mujally/gridbreak/blob/main/src/game/aiConvergence.ts"
click node_online_client "https://github.com/elias-mujally/gridbreak/blob/main/src/online/client.ts"
click node_protocol "https://github.com/elias-mujally/gridbreak/blob/main/src/online/protocol.ts"
click node_identity "https://github.com/elias-mujally/gridbreak/blob/main/src/online/identity.ts"
click node_worker "https://github.com/elias-mujally/gridbreak/blob/main/worker/index.ts"
click node_room "https://github.com/elias-mujally/gridbreak/blob/main/src/online/room.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_app,node_setup,node_convergence_ui,node_online_ui,node_online_race_ui toneBlue
class node_configuration,node_state,node_engine,node_movement,node_walls,node_pathfinding,node_rush,node_tiles,node_views,node_ai,node_ai_rush,node_ai_convergence toneAmber
class node_online_client,node_protocol,node_identity toneMint
class node_worker,node_room,node_durable_storage toneRose
class node_player toneIndigo
```

## Components

### Game experience

- [Local match UI](https://github.com/elias-mujally/gridbreak/blob/main/src/ui/App.tsx): `src/ui/App.tsx`
- [Mode and setup picker](https://github.com/elias-mujally/gridbreak/blob/main/src/ui/ModePicker.tsx): `src/ui/ModePicker.tsx`
- [Convergence board](https://github.com/elias-mujally/gridbreak/blob/main/src/ui/ConvergenceMatch.tsx): `src/ui/ConvergenceMatch.tsx`
- [Online match UI](https://github.com/elias-mujally/gridbreak/blob/main/src/ui/OnlineApp.tsx): `src/ui/OnlineApp.tsx`
- [Online race board](https://github.com/elias-mujally/gridbreak/blob/main/src/ui/OnlineRaceMatch.tsx): `src/ui/OnlineRaceMatch.tsx`

### Shared game rules

- [Modes and map capabilities](https://github.com/elias-mujally/gridbreak/blob/main/src/game/modes.ts): `src/game/modes.ts`
- [Match state and setup](https://github.com/elias-mujally/gridbreak/blob/main/src/game/state.ts): `src/game/state.ts`
- [Action engine](https://github.com/elias-mujally/gridbreak/blob/main/src/game/engine.ts): `src/game/engine.ts`
- [Movement rules](https://github.com/elias-mujally/gridbreak/blob/main/src/game/movement.ts): `src/game/movement.ts`
- [Wall legality](https://github.com/elias-mujally/gridbreak/blob/main/src/game/walls.ts): `src/game/walls.ts`
- [Route search](https://github.com/elias-mujally/gridbreak/blob/main/src/game/pathfinding.ts): `src/game/pathfinding.ts`
- [Rush actions and rewards](https://github.com/elias-mujally/gridbreak/blob/main/src/game/rush.ts): `src/game/rush.ts`
- [Rush tiles](https://github.com/elias-mujally/gridbreak/blob/main/src/game/tiles.ts): `src/game/tiles.ts`
- [Player-specific views](https://github.com/elias-mujally/gridbreak/blob/main/src/game/view.ts): `src/game/view.ts`
- [AI controller](https://github.com/elias-mujally/gridbreak/blob/main/src/game/ai.ts): `src/game/ai.ts`
- [Rush AI strategy](https://github.com/elias-mujally/gridbreak/blob/main/src/game/aiRush.ts): `src/game/aiRush.ts`
- [Convergence AI](https://github.com/elias-mujally/gridbreak/blob/main/src/game/aiConvergence.ts): `src/game/aiConvergence.ts`

### Online play

- [Browser room client](https://github.com/elias-mujally/gridbreak/blob/main/src/online/client.ts): `src/online/client.ts`
- [Online protocol](https://github.com/elias-mujally/gridbreak/blob/main/src/online/protocol.ts): `src/online/protocol.ts`
- [Guest identity](https://github.com/elias-mujally/gridbreak/blob/main/src/online/identity.ts): `src/online/identity.ts`

### Room service

- [Worker admission and transport](https://github.com/elias-mujally/gridbreak/blob/main/worker/index.ts): `worker/index.ts`
- [Authoritative room](https://github.com/elias-mujally/gridbreak/blob/main/src/online/room.ts): `src/online/room.ts`
- **Durable Object storage**

### Other components

- **Player**

## Connections

- Player → Mode and setup picker: chooses match (evidence: `README.md`)
- Mode and setup picker → Local match UI: starts local match (evidence: `src/ui/App.tsx`)
- Mode and setup picker → Modes and map capabilities: checks capabilities (evidence: `src/game/modes.ts`)
- Local match UI → Action engine: applies actions (evidence: `src/ui/App.tsx`)
- Local match UI → AI controller: requests AI action (evidence: `src/game/ai.ts`)
- Local match UI → Convergence board: renders Convergence (evidence: `src/ui/App.tsx`)
- Local match UI → Online match UI: opens online play (evidence: `src/ui/App.tsx`)
- Convergence board → Action engine: applies local action (evidence: `src/ui/App.tsx`)
- Match state and setup → Modes and map capabilities: builds configured match (evidence: `src/game/state.ts`)
- Match state and setup → Rush tiles: generates Rush tiles (evidence: `src/game/state.ts`)
- Action engine → Movement rules: checks legal moves (evidence: `src/game/engine.ts`)
- Action engine → Wall legality: checks wall legality (evidence: `src/game/engine.ts`)
- Action engine → Rush actions and rewards: dispatches Rush actions (evidence: `src/game/engine.ts`)
- Movement rules → Wall legality: checks steps (evidence: `src/game/movement.ts`)
- Wall legality → Route search: preserves routes (evidence: `src/game/walls.ts`)
- Route search → Wall legality: checks traversable edges (evidence: `src/game/pathfinding.ts`)
- AI controller → Rush AI strategy: delegates Rush strategy (evidence: `src/game/ai.ts`)
- AI controller → Convergence AI: delegates Convergence strategy (evidence: `src/game/ai.ts`)
- Rush AI strategy → Player-specific views: evaluates player view (evidence: `src/game/aiRush.ts`)
- Convergence AI → Route search: scores routes (evidence: `src/game/aiConvergence.ts`)
- Online match UI → Browser room client: uses room client (evidence: `src/ui/OnlineApp.tsx`)
- Online match UI → Online race board: renders race match (evidence: `src/ui/OnlineApp.tsx`)
- Online race board → Player-specific views: derives movement board (evidence: `src/ui/OnlineRaceMatch.tsx`)
- Browser room client → Online protocol: encodes room messages (evidence: `src/online/client.ts`)
- Player → Online match UI: joins online room (evidence: `README.md`)
- Browser room client → Worker admission and transport: connects by WebSocket (evidence: `README.md`)
- Worker admission and transport → Guest identity: creates guest identity (evidence: `worker/index.ts`)
- Worker admission and transport → Online protocol: validates messages (evidence: `worker/index.ts`)
- Worker admission and transport → Authoritative room: dispatches room actions (evidence: `worker/index.ts`)
- Authoritative room → Action engine: executes authoritative actions (evidence: `src/online/room.ts`)
- Authoritative room → Player-specific views: projects player views (evidence: `src/online/room.ts`)
- Authoritative room → Durable Object storage: persists room state (evidence: `README.md`)
