# volkan35koc/from-village-to-city architecture

> Architecture diagram of the GitHub repository volkan35koc/from-village-to-city, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/volkan35koc/from-village-to-city
- Repository: https://github.com/volkan35koc/from-village-to-city

## Overview

This is a real-time, multiplayer Catan-style game with online rooms and a bot-game option. Players enter through the menu, create or join a room (or request a bot game), then use the game view to interact with the board, take turns, trade, play development cards, and chat. The frontend exchanges game events and state over Socket.IO; the backend manages rooms and delegates game actions to game instances, whose domain model uses a board and player records. Help and building-cost references are also part of the client. Some feature wiring is unsampled, so uncertain links are omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/App.jsx) (Application shell), [`frontend/src/components/Game.jsx`](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Game.jsx) (Game view), [`frontend/src/components/Board/HexGrid.jsx`](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/HexGrid.jsx) (Board renderer), [`frontend/src/context/GameContext.jsx`](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/context/GameContext.jsx) (Game state context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["Application shell<br/>[App.jsx]"]
  node_menu["Main menu<br/>[MainMenu.jsx]"]
  node_lobby["Online lobby<br/>[Lobby.jsx]"]
  node_botsetup["Bot setup<br/>[BotSetup.jsx]"]
  node_help["Help modal<br/>[HelpModal.jsx]"]
  node_gameui["Game view<br/>[Game.jsx]"]
  node_boardui["Board renderer<br/>[HexGrid.jsx]"]
  node_hex["Hex tile<br/>[Hex.jsx]"]
  node_intersection["Intersection<br/>[Intersection.jsx]"]
  node_edge["Road edge<br/>[Edge.jsx]"]
  node_tradeui["Trade dialog<br/>[TradeModal.jsx]"]
  node_cardsui["Development cards<br/>[DevCardDisplay.jsx]"]
  node_chatui["Game chat<br/>[Chat.jsx]"]
  node_costsui["Building costs<br/>[BuildingCosts.jsx]"]
end

subgraph group_transport["Realtime transport"]
  node_socketcontext["Socket provider<br/>[SocketContext.jsx]"]
  node_gamecontext["Game state context<br/>[GameContext.jsx]"]
  node_socketserver["Socket.IO server<br/>[server.js]"]
end

subgraph group_runtime["Game runtime"]
  node_manager["Room manager<br/>[GameManager.js]"]
end

subgraph group_domain["Game domain"]
  node_game["Game rules and actions<br/>[Game.js]"]
  node_board["Board model<br/>[Board.js]"]
  node_playerdomain["Player model<br/>[Player.js]"]
end

node_player(("Player"))

node_player -->|"uses"| node_app
node_app -->|"renders"| node_menu
node_app -->|"renders"| node_lobby
node_app -->|"renders"| node_botsetup
node_app -->|"renders"| node_help
node_app -->|"renders"| node_gameui
node_app -->|"reads state"| node_gamecontext
node_gamecontext -->|"uses socket"| node_socketcontext
node_gameui -->|"reads and acts"| node_gamecontext
node_gameui -->|"renders"| node_boardui
node_boardui -->|"renders"| node_hex
node_boardui -->|"renders"| node_intersection
node_boardui -->|"renders"| node_edge
node_gameui -->|"renders"| node_tradeui
node_gameui -->|"renders"| node_cardsui
node_gameui -->|"renders"| node_chatui
node_gameui -->|"renders"| node_costsui
node_socketcontext -.->|"connects to"| node_socketserver
node_gamecontext -.->|"sends game events"| node_manager
node_socketserver -->|"registers connections"| node_manager
node_manager -->|"creates and dispatches"| node_game
node_game -->|"uses board"| node_board
node_game -->|"uses player records"| node_playerdomain

click node_app "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/App.jsx"
click node_menu "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/MainMenu.jsx"
click node_lobby "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Lobby.jsx"
click node_botsetup "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/BotSetup.jsx"
click node_help "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/HelpModal.jsx"
click node_gameui "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Game.jsx"
click node_boardui "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/HexGrid.jsx"
click node_hex "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/Hex.jsx"
click node_intersection "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/Intersection.jsx"
click node_edge "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/Edge.jsx"
click node_tradeui "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/TradeModal.jsx"
click node_cardsui "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/DevCardDisplay.jsx"
click node_chatui "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Chat.jsx"
click node_costsui "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/BuildingCosts.jsx"
click node_socketcontext "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/context/SocketContext.jsx"
click node_gamecontext "https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/context/GameContext.jsx"
click node_socketserver "https://github.com/volkan35koc/from-village-to-city/blob/main/backend/server.js"
click node_manager "https://github.com/volkan35koc/from-village-to-city/blob/main/backend/game/GameManager.js"
click node_game "https://github.com/volkan35koc/from-village-to-city/blob/main/backend/game/Game.js"
click node_board "https://github.com/volkan35koc/from-village-to-city/blob/main/backend/game/Board.js"
click node_playerdomain "https://github.com/volkan35koc/from-village-to-city/blob/main/backend/game/Player.js"

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_menu,node_lobby,node_botsetup,node_help,node_gameui,node_boardui,node_hex,node_intersection,node_edge,node_tradeui,node_cardsui,node_chatui,node_costsui toneBlue
class node_socketcontext,node_gamecontext,node_socketserver toneAmber
class node_manager toneMint
class node_game,node_board,node_playerdomain toneRose
class node_player toneIndigo
```

## Components

### Client experience

- [Application shell](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Main menu](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/MainMenu.jsx): `frontend/src/components/MainMenu.jsx`
- [Online lobby](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Lobby.jsx): `frontend/src/components/Lobby.jsx`
- [Bot setup](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/BotSetup.jsx): `frontend/src/components/BotSetup.jsx`
- [Help modal](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/HelpModal.jsx): `frontend/src/components/HelpModal.jsx`
- [Game view](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Game.jsx): `frontend/src/components/Game.jsx`
- [Board renderer](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/HexGrid.jsx): `frontend/src/components/Board/HexGrid.jsx`
- [Hex tile](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/Hex.jsx): `frontend/src/components/Board/Hex.jsx`
- [Intersection](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/Intersection.jsx): `frontend/src/components/Board/Intersection.jsx`
- [Road edge](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Board/Edge.jsx): `frontend/src/components/Board/Edge.jsx`
- [Trade dialog](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/TradeModal.jsx): `frontend/src/components/TradeModal.jsx`
- [Development cards](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/DevCardDisplay.jsx): `frontend/src/components/DevCardDisplay.jsx`
- [Game chat](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/Chat.jsx): `frontend/src/components/Chat.jsx`
- [Building costs](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/components/BuildingCosts.jsx): `frontend/src/components/BuildingCosts.jsx`

### Realtime transport

- [Socket provider](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/context/SocketContext.jsx): `frontend/src/context/SocketContext.jsx`
- [Game state context](https://github.com/volkan35koc/from-village-to-city/blob/main/frontend/src/context/GameContext.jsx): `frontend/src/context/GameContext.jsx`
- [Socket.IO server](https://github.com/volkan35koc/from-village-to-city/blob/main/backend/server.js): `backend/server.js`

### Game runtime

- [Room manager](https://github.com/volkan35koc/from-village-to-city/blob/main/backend/game/GameManager.js): `backend/game/GameManager.js`

### Game domain

- [Game rules and actions](https://github.com/volkan35koc/from-village-to-city/blob/main/backend/game/Game.js): `backend/game/Game.js`
- [Board model](https://github.com/volkan35koc/from-village-to-city/blob/main/backend/game/Board.js): `backend/game/Board.js`
- [Player model](https://github.com/volkan35koc/from-village-to-city/blob/main/backend/game/Player.js): `backend/game/Player.js`

### Other components

- **Player**

## Connections

- Player → Application shell: uses
- Application shell → Main menu: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Online lobby: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Bot setup: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Help modal: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Game view: renders (evidence: `frontend/src/App.jsx`)
- Application shell → Game state context: reads state (evidence: `frontend/src/App.jsx`)
- Game state context → Socket provider: uses socket (evidence: `frontend/src/context/GameContext.jsx`)
- Game view → Game state context: reads and acts (evidence: `frontend/src/components/Game.jsx`)
- Game view → Board renderer: renders (evidence: `frontend/src/components/Game.jsx`)
- Board renderer → Hex tile: renders (evidence: `frontend/src/components/Board/HexGrid.jsx`)
- Board renderer → Intersection: renders (evidence: `frontend/src/components/Board/HexGrid.jsx`)
- Board renderer → Road edge: renders (evidence: `frontend/src/components/Board/HexGrid.jsx`)
- Game view → Trade dialog: renders (evidence: `frontend/src/components/Game.jsx`)
- Game view → Development cards: renders (evidence: `frontend/src/components/Game.jsx`)
- Game view → Game chat: renders (evidence: `frontend/src/components/Game.jsx`)
- Game view → Building costs: renders (evidence: `frontend/src/components/Game.jsx`)
- Socket provider → Socket.IO server: connects to
- Game state context → Room manager: sends game events
- Socket.IO server → Room manager: registers connections (evidence: `backend/server.js`)
- Room manager → Game rules and actions: creates and dispatches (evidence: `backend/game/GameManager.js`)
- Game rules and actions → Board model: uses board (evidence: `backend/game/Game.js`)
- Game rules and actions → Player model: uses player records (evidence: `backend/game/Game.js`)
