# nickrusso-os/battleship-game- architecture

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

- Interactive diagram: https://gitdiagram.com/nickrusso-os/battleship-game-
- Repository: https://github.com/nickrusso-os/battleship-game-

## Overview

Covey.Town is a browser-based virtual meeting space: participants select or create a town, join its shared 2D map, move among other players, and enter proximity conversations or viewing areas, with games as another interactable. The frontend maintains town/player/interactable state over Socket.IO; the service manages town state and broadcasts updates. Video calling is a distinct Twilio-backed capability integrated into the town experience. The map reflects documented capabilities and sampled wiring; unsampled subsystem links are shown only where their ownership is clear from the README or entry-point source.

Main entry points: [`townService/src/town/TownsController.ts`](https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/town/TownsController.ts) (Town routes), [`frontend/src/classes/TownController.ts`](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/TownController.ts) (Town controller), [`frontend/src/components/Town/TownMap.tsx`](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/TownMap.tsx) (Town map), [`frontend/src/App.tsx`](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/App.tsx) (App experience)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Town frontend"]
  node_app["App experience<br/>[App.tsx]"]
  node_login["Town login<br/>[Login.tsx]"]
  node_townselect["Town selection<br/>[TownSelection.tsx]"]
  node_townmap["Town map<br/>[TownMap.tsx]"]
  node_scene["Map scene<br/>[TownGameScene.ts]"]
  node_social["Social sidebar<br/>[SocialSidebar.tsx]"]
  node_interactables["Interactable UI"]
  node_battleui["Battleship UI<br/>[BattleShipArea.tsx]"]
  node_socket["Socket.IO client<br/>[TownController.ts]"]
  node_restclient["Towns REST client<br/>[App.tsx]"]
end

subgraph group_service["Town service"]
  node_server["Service server<br/>[Server.ts]"]
  node_townroutes["Town routes<br/>[TownsController.ts]"]
  node_towns["Town state<br/>[Town.ts]"]
  node_players["Player state<br/>[Player.ts]"]
  node_store[("Towns store<br/>[TownsStore.ts]")]
  node_games["Game logic<br/>[GameAreaFactory.ts]"]
  node_twilioclient["Twilio video client<br/>[TwilioVideo.ts]"]
end

subgraph group_video["Video calling"]
  node_videooverlay["Video overlay<br/>[VideoOverlay.tsx]"]
  node_videoprovider["Video provider<br/>[index.tsx]"]
  node_videoui["Call controls<br/>[Room.tsx]"]
end

subgraph group_state["Domain state"]
  node_towncontroller["Town controller<br/>[TownController.ts]"]
  node_playercontroller["Player controller"]
  node_areacontrollers["Area controllers"]
  node_battlecontroller["Battleship controller"]
end

node_participant(("Participant"))
node_twilio{{"Twilio Video"}}

node_participant -->|"opens"| node_app
node_app -->|"shows"| node_login
node_login -->|"selects town"| node_townselect
node_townselect -->|"lists towns"| node_restclient
node_restclient -->|"REST requests"| node_server
node_server -->|"routes requests"| node_townroutes
node_townroutes -->|"reads/writes towns"| node_store
node_townroutes -->|"joins town"| node_towns
node_towns -->|"manages players"| node_players
node_towns -->|"manages games"| node_games
node_server -->|"dispatches sockets"| node_townroutes
node_townroutes -->|"finds town"| node_store
node_townroutes -->|"initializes client"| node_socket
node_socket -->|"socket events"| node_towncontroller
node_towncontroller -->|"sends commands"| node_socket
node_towncontroller -->|"provides town state"| node_townmap
node_townmap -->|"renders map"| node_scene
node_scene -->|"updates movement"| node_playercontroller
node_townmap -->|"shows players"| node_social
node_townmap -->|"renders areas"| node_interactables
node_towncontroller -->|"creates controllers"| node_areacontrollers
node_areacontrollers -->|"supplies area state"| node_interactables
node_interactables -->|"issues commands"| node_towncontroller
node_townmap -->|"renders game"| node_battleui
node_battleui -->|"reads game state"| node_battlecontroller
node_battlecontroller -->|"sends game moves"| node_towncontroller
node_app -->|"configures provider"| node_videoprovider
node_app -->|"shows call"| node_videooverlay
node_videooverlay -->|"renders room UI"| node_videoui
node_videoprovider -->|"connects media"| node_twilio
node_towns -->|"creates video token"| node_twilioclient
node_twilioclient -->|"requests token"| node_twilio

click node_app "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/App.tsx"
click node_login "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Login/Login.tsx"
click node_townselect "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Login/TownSelection.tsx"
click node_townmap "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/TownMap.tsx"
click node_scene "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/TownGameScene.ts"
click node_social "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/SocialSidebar/SocialSidebar.tsx"
click node_interactables "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/interactables/ConversationArea.ts"
click node_battleui "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/interactables/BattleShip/BattleShipArea.tsx"
click node_towncontroller "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/TownController.ts"
click node_playercontroller "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/PlayerController.ts"
click node_areacontrollers "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/interactable/InteractableAreaController.ts"
click node_battlecontroller "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/interactable/BattleShipAreaController.ts"
click node_socket "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/TownController.ts"
click node_restclient "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/App.tsx"
click node_server "https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/Server.ts"
click node_townroutes "https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/town/TownsController.ts"
click node_towns "https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/town/Town.ts"
click node_players "https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/lib/Player.ts"
click node_store "https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/lib/TownsStore.ts"
click node_games "https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/town/games/GameAreaFactory.ts"
click node_twilioclient "https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/lib/TwilioVideo.ts"
click node_videooverlay "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/VideoCall/VideoOverlay/VideoOverlay.tsx"
click node_videoprovider "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/VideoCall/VideoFrontend/components/VideoProvider/index.tsx"
click node_videoui "https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/VideoCall/VideoFrontend/components/Room/Room.tsx"

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_login,node_townselect,node_townmap,node_scene,node_social,node_interactables,node_battleui,node_socket,node_restclient toneBlue
class node_server,node_townroutes,node_towns,node_players,node_store,node_games,node_twilioclient toneAmber
class node_videooverlay,node_videoprovider,node_videoui toneMint
class node_towncontroller,node_playercontroller,node_areacontrollers,node_battlecontroller toneRose
class node_participant,node_twilio toneIndigo
```

## Components

### Town frontend

- [App experience](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Town login](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Login/Login.tsx): `frontend/src/components/Login/Login.tsx`
- [Town selection](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Login/TownSelection.tsx): `frontend/src/components/Login/TownSelection.tsx`
- [Town map](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/TownMap.tsx): `frontend/src/components/Town/TownMap.tsx`
- [Map scene](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/TownGameScene.ts): `frontend/src/components/Town/TownGameScene.ts`
- [Social sidebar](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/SocialSidebar/SocialSidebar.tsx): `frontend/src/components/SocialSidebar/SocialSidebar.tsx`
- [Interactable UI](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/interactables/ConversationArea.ts): `frontend/src/components/Town/interactables/ConversationArea.ts`
- [Battleship UI](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/Town/interactables/BattleShip/BattleShipArea.tsx): `frontend/src/components/Town/interactables/BattleShip/BattleShipArea.tsx`
- [Socket.IO client](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/TownController.ts): `frontend/src/classes/TownController.ts`
- [Towns REST client](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Town service

- [Service server](https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/Server.ts): `townService/src/Server.ts`
- [Town routes](https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/town/TownsController.ts): `townService/src/town/TownsController.ts`
- [Town state](https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/town/Town.ts): `townService/src/town/Town.ts`
- [Player state](https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/lib/Player.ts): `townService/src/lib/Player.ts`
- [Towns store](https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/lib/TownsStore.ts): `townService/src/lib/TownsStore.ts`
- [Game logic](https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/town/games/GameAreaFactory.ts): `townService/src/town/games/GameAreaFactory.ts`
- [Twilio video client](https://github.com/nickrusso-os/battleship-game-/blob/main/townService/src/lib/TwilioVideo.ts): `townService/src/lib/TwilioVideo.ts`

### Video calling

- [Video overlay](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/VideoCall/VideoOverlay/VideoOverlay.tsx): `frontend/src/components/VideoCall/VideoOverlay/VideoOverlay.tsx`
- [Video provider](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/VideoCall/VideoFrontend/components/VideoProvider/index.tsx): `frontend/src/components/VideoCall/VideoFrontend/components/VideoProvider/index.tsx`
- [Call controls](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/components/VideoCall/VideoFrontend/components/Room/Room.tsx): `frontend/src/components/VideoCall/VideoFrontend/components/Room/Room.tsx`

### Domain state

- [Town controller](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/TownController.ts): `frontend/src/classes/TownController.ts`
- [Player controller](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/PlayerController.ts): `frontend/src/classes/PlayerController.ts`
- [Area controllers](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/interactable/InteractableAreaController.ts): `frontend/src/classes/interactable/InteractableAreaController.ts`
- [Battleship controller](https://github.com/nickrusso-os/battleship-game-/blob/main/frontend/src/classes/interactable/BattleShipAreaController.ts): `frontend/src/classes/interactable/BattleShipAreaController.ts`

### Other components

- **Participant**
- **Twilio Video**

## Connections

- Participant → App experience: opens
- App experience → Town login: shows
- Town login → Town selection: selects town
- Town selection → Towns REST client: lists towns
- Towns REST client → Service server: REST requests
- Service server → Town routes: routes requests
- Town routes → Towns store: reads/writes towns
- Town routes → Town state: joins town
- Town state → Player state: manages players
- Town state → Game logic: manages games
- Service server → Town routes: dispatches sockets
- Town routes → Towns store: finds town
- Town routes → Socket.IO client: initializes client
- Socket.IO client → Town controller: socket events
- Town controller → Socket.IO client: sends commands
- Town controller → Town map: provides town state
- Town map → Map scene: renders map
- Map scene → Player controller: updates movement
- Town map → Social sidebar: shows players
- Town map → Interactable UI: renders areas
- Town controller → Area controllers: creates controllers
- Area controllers → Interactable UI: supplies area state
- Interactable UI → Town controller: issues commands
- Town map → Battleship UI: renders game
- Battleship UI → Battleship controller: reads game state
- Battleship controller → Town controller: sends game moves
- App experience → Video provider: configures provider
- App experience → Video overlay: shows call
- Video overlay → Call controls: renders room UI
- Video provider → Twilio Video: connects media
- Town state → Twilio video client: creates video token
- Twilio video client → Twilio Video: requests token