# msm691/epitopia architecture

> Architecture diagram of the GitHub repository msm691/epitopia, 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/msm691/epitopia
- Repository: https://github.com/msm691/epitopia

## Overview

Epitopia is a browser-based multiplayer 4X strategy game. Players browse or create lobbies, join a match, then explore a generated map and submit turn-based actions; the server synchronizes game state to clients. The graph includes the documented strategy systems and the sampled engine, shared protocol, and 3D client layers. Several server-to-engine and UI-to-renderer connections are not shown in the excerpts or reference index, so they are omitted or marked unverified.

Main entry points: [`engine/src/applyAction.ts`](https://github.com/msm691/epitopia/blob/main/engine/src/applyAction.ts) (Action resolution), [`server/src/gameServer.ts`](https://github.com/msm691/epitopia/blob/main/server/src/gameServer.ts) (Game server), [`client/src/net.ts`](https://github.com/msm691/epitopia/blob/main/client/src/net.ts) (Socket client), [`shared/src/protocol.ts`](https://github.com/msm691/epitopia/blob/main/shared/src/protocol.ts) (Socket protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_app["App shell<br/>[App.tsx]"]
  node_network["Socket client<br/>[net.ts]"]
  node_lobby["Lobby browser<br/>[LobbyBrowser.tsx]"]
  node_gameview["Game interface<br/>[GameView.tsx]"]
  node_chat["Chat<br/>[Chat.tsx]"]
  node_mappreview["Map preview<br/>[MapPreview.tsx]"]
  node_scene["3D scene<br/>[Scene3D.tsx]"]
  node_terrain["Terrain renderer<br/>[Terrain.tsx]"]
  node_buildings["Building renderer<br/>[Buildings.tsx]"]
  node_effects["Effects renderer<br/>[Effects.tsx]"]
  node_unitsrender["Unit renderer<br/>[Units.tsx]"]
  node_models["3D models<br/>[models.ts]"]
  node_projection["Map projection<br/>[projection.ts]"]
  node_audio["Audio<br/>[audio.ts]"]
end

subgraph group_engine["Game engine"]
  node_state["Initial game state<br/>[state.ts]"]
  node_mapgen["Map generation<br/>[generateMap.ts]"]
  node_actionapply["Action resolution<br/>[applyAction.ts]"]
  node_legality["Action validation<br/>[isLegal.ts]"]
  node_ai["AI decisions<br/>[ai.ts]"]
  node_combat["Combat rules<br/>[combat.ts]"]
  node_economy["Economy rules<br/>[economy.ts]"]
  node_technology["Technology rules<br/>[tech.ts]"]
  node_pathfinding["Pathfinding<br/>[pathfinding.ts]"]
  node_sages["Sage encounters<br/>[sages.ts]"]
  node_victory["Victory rules<br/>[victory.ts]"]
  node_rng["Seeded randomness<br/>[rng.ts]"]
end

subgraph group_shared["Shared contracts"]
  node_protocol["Socket protocol<br/>[protocol.ts]"]
  node_actions["Game actions<br/>[actions.ts]"]
  node_types["Game data types<br/>[types.ts]"]
end

subgraph group_server["Multiplayer server"]
  node_server["Game server<br/>[gameServer.ts]"]
end

node_player(("Player"))

node_player -->|"plays in"| node_app
node_app -->|"uses"| node_network
node_player -->|"browses lobbies"| node_lobby
node_player -->|"plays match"| node_gameview
node_gameview -->|"plays audio"| node_audio
node_network -->|"sends socket events"| node_server
node_server -->|"synchronizes state"| node_network
node_server -->|"uses event contract"| node_protocol
node_network -->|"uses event contract"| node_protocol
node_protocol -->|"defines action events"| node_actions
node_protocol -->|"defines state payloads"| node_types
node_actions -->|"uses data types"| node_types
node_server -.->|"routes actions"| node_actionapply
node_state -->|"generates map"| node_mapgen
node_state -->|"computes starting income"| node_economy
node_mapgen -->|"seeds generation"| node_rng
node_actionapply -->|"validates action"| node_legality
node_actionapply -->|"computes income"| node_economy
node_actionapply -->|"resolves research"| node_technology
node_actionapply -->|"resolves encounter"| node_sages
node_ai -->|"checks legality"| node_legality
node_ai -->|"scores attacks"| node_combat
node_ai -->|"checks unlocks"| node_technology
node_economy -->|"checks trade routes"| node_pathfinding
node_scene -->|"uses projection"| node_projection
node_terrain -->|"projects tiles"| node_projection
node_buildings -->|"projects buildings"| node_projection
node_buildings -->|"uses models"| node_models
node_effects -->|"projects effects"| node_projection
node_unitsrender -->|"uses models"| node_models

click node_app "https://github.com/msm691/epitopia/blob/main/client/src/App.tsx"
click node_network "https://github.com/msm691/epitopia/blob/main/client/src/net.ts"
click node_lobby "https://github.com/msm691/epitopia/blob/main/client/src/LobbyBrowser.tsx"
click node_gameview "https://github.com/msm691/epitopia/blob/main/client/src/GameView.tsx"
click node_chat "https://github.com/msm691/epitopia/blob/main/client/src/Chat.tsx"
click node_mappreview "https://github.com/msm691/epitopia/blob/main/client/src/MapPreview.tsx"
click node_scene "https://github.com/msm691/epitopia/blob/main/client/src/three/Scene3D.tsx"
click node_terrain "https://github.com/msm691/epitopia/blob/main/client/src/three/Terrain.tsx"
click node_buildings "https://github.com/msm691/epitopia/blob/main/client/src/three/Buildings.tsx"
click node_effects "https://github.com/msm691/epitopia/blob/main/client/src/three/Effects.tsx"
click node_unitsrender "https://github.com/msm691/epitopia/blob/main/client/src/three/Units.tsx"
click node_models "https://github.com/msm691/epitopia/blob/main/client/src/three/models.ts"
click node_projection "https://github.com/msm691/epitopia/blob/main/client/src/three/projection.ts"
click node_audio "https://github.com/msm691/epitopia/blob/main/client/src/audio.ts"
click node_server "https://github.com/msm691/epitopia/blob/main/server/src/gameServer.ts"
click node_protocol "https://github.com/msm691/epitopia/blob/main/shared/src/protocol.ts"
click node_actions "https://github.com/msm691/epitopia/blob/main/shared/src/actions.ts"
click node_types "https://github.com/msm691/epitopia/blob/main/shared/src/types.ts"
click node_state "https://github.com/msm691/epitopia/blob/main/engine/src/state.ts"
click node_mapgen "https://github.com/msm691/epitopia/blob/main/engine/src/generateMap.ts"
click node_actionapply "https://github.com/msm691/epitopia/blob/main/engine/src/applyAction.ts"
click node_legality "https://github.com/msm691/epitopia/blob/main/engine/src/isLegal.ts"
click node_ai "https://github.com/msm691/epitopia/blob/main/engine/src/ai.ts"
click node_combat "https://github.com/msm691/epitopia/blob/main/engine/src/combat.ts"
click node_economy "https://github.com/msm691/epitopia/blob/main/engine/src/economy.ts"
click node_technology "https://github.com/msm691/epitopia/blob/main/engine/src/tech.ts"
click node_pathfinding "https://github.com/msm691/epitopia/blob/main/engine/src/pathfinding.ts"
click node_sages "https://github.com/msm691/epitopia/blob/main/engine/src/sages.ts"
click node_victory "https://github.com/msm691/epitopia/blob/main/engine/src/victory.ts"
click node_rng "https://github.com/msm691/epitopia/blob/main/engine/src/rng.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_network,node_lobby,node_gameview,node_chat,node_mappreview,node_scene,node_terrain,node_buildings,node_effects,node_unitsrender,node_models,node_projection,node_audio toneBlue
class node_state,node_mapgen,node_actionapply,node_legality,node_ai,node_combat,node_economy,node_technology,node_pathfinding,node_sages,node_victory,node_rng toneAmber
class node_protocol,node_actions,node_types toneMint
class node_server toneRose
class node_player toneIndigo
```

## Components

### Browser client

- [App shell](https://github.com/msm691/epitopia/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Socket client](https://github.com/msm691/epitopia/blob/main/client/src/net.ts): `client/src/net.ts`
- [Lobby browser](https://github.com/msm691/epitopia/blob/main/client/src/LobbyBrowser.tsx): `client/src/LobbyBrowser.tsx`
- [Game interface](https://github.com/msm691/epitopia/blob/main/client/src/GameView.tsx): `client/src/GameView.tsx`
- [Chat](https://github.com/msm691/epitopia/blob/main/client/src/Chat.tsx): `client/src/Chat.tsx`
- [Map preview](https://github.com/msm691/epitopia/blob/main/client/src/MapPreview.tsx): `client/src/MapPreview.tsx`
- [3D scene](https://github.com/msm691/epitopia/blob/main/client/src/three/Scene3D.tsx): `client/src/three/Scene3D.tsx`
- [Terrain renderer](https://github.com/msm691/epitopia/blob/main/client/src/three/Terrain.tsx): `client/src/three/Terrain.tsx`
- [Building renderer](https://github.com/msm691/epitopia/blob/main/client/src/three/Buildings.tsx): `client/src/three/Buildings.tsx`
- [Effects renderer](https://github.com/msm691/epitopia/blob/main/client/src/three/Effects.tsx): `client/src/three/Effects.tsx`
- [Unit renderer](https://github.com/msm691/epitopia/blob/main/client/src/three/Units.tsx): `client/src/three/Units.tsx`
- [3D models](https://github.com/msm691/epitopia/blob/main/client/src/three/models.ts): `client/src/three/models.ts`
- [Map projection](https://github.com/msm691/epitopia/blob/main/client/src/three/projection.ts): `client/src/three/projection.ts`
- [Audio](https://github.com/msm691/epitopia/blob/main/client/src/audio.ts): `client/src/audio.ts`

### Game engine

- [Initial game state](https://github.com/msm691/epitopia/blob/main/engine/src/state.ts): `engine/src/state.ts`
- [Map generation](https://github.com/msm691/epitopia/blob/main/engine/src/generateMap.ts): `engine/src/generateMap.ts`
- [Action resolution](https://github.com/msm691/epitopia/blob/main/engine/src/applyAction.ts): `engine/src/applyAction.ts`
- [Action validation](https://github.com/msm691/epitopia/blob/main/engine/src/isLegal.ts): `engine/src/isLegal.ts`
- [AI decisions](https://github.com/msm691/epitopia/blob/main/engine/src/ai.ts): `engine/src/ai.ts`
- [Combat rules](https://github.com/msm691/epitopia/blob/main/engine/src/combat.ts): `engine/src/combat.ts`
- [Economy rules](https://github.com/msm691/epitopia/blob/main/engine/src/economy.ts): `engine/src/economy.ts`
- [Technology rules](https://github.com/msm691/epitopia/blob/main/engine/src/tech.ts): `engine/src/tech.ts`
- [Pathfinding](https://github.com/msm691/epitopia/blob/main/engine/src/pathfinding.ts): `engine/src/pathfinding.ts`
- [Sage encounters](https://github.com/msm691/epitopia/blob/main/engine/src/sages.ts): `engine/src/sages.ts`
- [Victory rules](https://github.com/msm691/epitopia/blob/main/engine/src/victory.ts): `engine/src/victory.ts`
- [Seeded randomness](https://github.com/msm691/epitopia/blob/main/engine/src/rng.ts): `engine/src/rng.ts`

### Shared contracts

- [Socket protocol](https://github.com/msm691/epitopia/blob/main/shared/src/protocol.ts): `shared/src/protocol.ts`
- [Game actions](https://github.com/msm691/epitopia/blob/main/shared/src/actions.ts): `shared/src/actions.ts`
- [Game data types](https://github.com/msm691/epitopia/blob/main/shared/src/types.ts): `shared/src/types.ts`

### Multiplayer server

- [Game server](https://github.com/msm691/epitopia/blob/main/server/src/gameServer.ts): `server/src/gameServer.ts`

### Other components

- **Player**

## Connections

- Player → App shell: plays in
- App shell → Socket client: uses (evidence: `client/src/App.tsx`)
- Player → Lobby browser: browses lobbies
- Player → Game interface: plays match
- Game interface → Audio: plays audio (evidence: `client/src/GameView.tsx`)
- Socket client → Game server: sends socket events
- Game server → Socket client: synchronizes state
- Game server → Socket protocol: uses event contract
- Socket client → Socket protocol: uses event contract
- Socket protocol → Game actions: defines action events (evidence: `shared/src/protocol.ts`)
- Socket protocol → Game data types: defines state payloads (evidence: `shared/src/protocol.ts`)
- Game actions → Game data types: uses data types (evidence: `shared/src/actions.ts`)
- Game server → Action resolution: routes actions · Inferred; not shown in the code that was read.
- Initial game state → Map generation: generates map (evidence: `engine/src/state.ts`)
- Initial game state → Economy rules: computes starting income (evidence: `engine/src/state.ts`)
- Map generation → Seeded randomness: seeds generation (evidence: `engine/src/generateMap.ts`)
- Action resolution → Action validation: validates action (evidence: `engine/src/applyAction.ts`)
- Action resolution → Economy rules: computes income (evidence: `engine/src/applyAction.ts`)
- Action resolution → Technology rules: resolves research (evidence: `engine/src/applyAction.ts`)
- Action resolution → Sage encounters: resolves encounter (evidence: `engine/src/applyAction.ts`)
- AI decisions → Action validation: checks legality (evidence: `engine/src/ai.ts`)
- AI decisions → Combat rules: scores attacks (evidence: `engine/src/ai.ts`)
- AI decisions → Technology rules: checks unlocks (evidence: `engine/src/ai.ts`)
- Economy rules → Pathfinding: checks trade routes (evidence: `engine/src/economy.ts`)
- 3D scene → Map projection: uses projection (evidence: `client/src/three/Scene3D.tsx`)
- Terrain renderer → Map projection: projects tiles (evidence: `client/src/three/Terrain.tsx`)
- Building renderer → Map projection: projects buildings (evidence: `client/src/three/Buildings.tsx`)
- Building renderer → 3D models: uses models (evidence: `client/src/three/Buildings.tsx`)
- Effects renderer → Map projection: projects effects (evidence: `client/src/three/Effects.tsx`)
- Unit renderer → 3D models: uses models (evidence: `client/src/three/Units.tsx`)
