# aeml/eidolon architecture

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

- Interactive diagram: https://gitdiagram.com/aeml/eidolon
- Repository: https://github.com/aeml/eidolon

## Overview

Eidolon is a browser-based multiplayer action RPG with an authoritative Go server. The principal workflow is player input in the browser, transmission of commands over WebSockets, server validation and simulation, persistence of durable state, and replication of canonical state back to clients for presentation. Gameplay spans combat, progression and dungeons, then social/economy and competitive activities; administration and the casino are additional capabilities. The README documents these responsibilities and protocol flow; several domain modules were not sampled, so their internal call wiring is not inferred.

Main entry points: [`server/internal/game/world.go`](https://github.com/aeml/eidolon/blob/master/server/internal/game/world.go) (Authoritative world), [`src/core/GameEngine.js`](https://github.com/aeml/eidolon/blob/master/src/core/GameEngine.js) (Game engine), [`src/core/NetworkManager.js`](https://github.com/aeml/eidolon/blob/master/src/core/NetworkManager.js) (Network manager), [`server/main.go`](https://github.com/aeml/eidolon/blob/master/server/main.go) (WebSocket server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_entry["Client startup<br/>[main.js]"]
  node_engine["Game engine<br/>[GameEngine.js]"]
  node_input_ui["Input and UI<br/>[UIManager.js]"]
  node_presentation["Rendering<br/>[RenderSystem.js]"]
  node_service_worker["Asset cache<br/>[sw.js]"]
end

subgraph group_transport["Realtime transport"]
  node_network["Network manager<br/>[NetworkManager.js]"]
  node_server["WebSocket server<br/>[main.go]"]
  node_dispatch["Command dispatch"]
  node_protocol["State protocol<br/>[state.proto]"]
end

subgraph group_simulation["Game simulation"]
  node_world["Authoritative world<br/>[world.go]"]
  node_combat["Combat and abilities"]
  node_dungeons["Dungeons and raids"]
  node_progression["Quests and rewards"]
end

subgraph group_domains["Player systems"]
  node_social["Party and guild"]
  node_economy["Items and trading"]
  node_competition["PvP and arenas"]
  node_casino["Casino games"]
  node_administration["Administration"]
end

subgraph group_storage["Persistent state"]
  node_persistence["Persistence layer"]
  node_mongo[("MongoDB")]
end

node_player(("Player"))

node_player -->|"starts game"| node_entry
node_entry -->|"creates"| node_engine
node_input_ui -->|"submits intent"| node_engine
node_engine -->|"sends commands"| node_network
node_network -->|"WebSocket commands"| node_server
node_server -->|"dispatches messages"| node_dispatch
node_dispatch -->|"applies actions"| node_world
node_world -->|"simulates combat"| node_combat
node_world -->|"advances encounters"| node_dungeons
node_world -->|"applies progression"| node_progression
node_world -->|"handles social play"| node_social
node_world -->|"handles transactions"| node_economy
node_world -->|"resolves PvP"| node_competition
node_world -->|"runs games"| node_casino
node_server -->|"handles admin requests"| node_administration
node_world -->|"stores game data"| node_persistence
node_persistence -->|"reads and writes"| node_mongo
node_server -->|"streams state"| node_network
node_network -->|"decodes state"| node_protocol
node_network -->|"updates state"| node_engine
node_engine -->|"updates presentation"| node_presentation
node_engine -->|"updates interface"| node_input_ui
node_entry -->|"registers cache"| node_service_worker

click node_entry "https://github.com/aeml/eidolon/blob/master/src/main.js"
click node_engine "https://github.com/aeml/eidolon/blob/master/src/core/GameEngine.js"
click node_input_ui "https://github.com/aeml/eidolon/blob/master/src/ui/UIManager.js"
click node_presentation "https://github.com/aeml/eidolon/blob/master/src/core/RenderSystem.js"
click node_network "https://github.com/aeml/eidolon/blob/master/src/core/NetworkManager.js"
click node_server "https://github.com/aeml/eidolon/blob/master/server/main.go"
click node_dispatch "https://github.com/aeml/eidolon/blob/master/server/message_handlers.go"
click node_world "https://github.com/aeml/eidolon/blob/master/server/internal/game/world.go"
click node_combat "https://github.com/aeml/eidolon/tree/master/server/internal/game"
click node_dungeons "https://github.com/aeml/eidolon/tree/master/server/internal/game"
click node_progression "https://github.com/aeml/eidolon/tree/master/server/internal/game"
click node_social "https://github.com/aeml/eidolon/tree/master/server/internal/game"
click node_economy "https://github.com/aeml/eidolon/tree/master/server/internal/game"
click node_competition "https://github.com/aeml/eidolon/tree/master/server/internal/game"
click node_casino "https://github.com/aeml/eidolon/tree/master/server/internal/game"
click node_administration "https://github.com/aeml/eidolon/blob/master/server/admin_console_handlers.go"
click node_persistence "https://github.com/aeml/eidolon/tree/master/server/internal/database"
click node_protocol "https://github.com/aeml/eidolon/blob/master/proto/state.proto"
click node_service_worker "https://github.com/aeml/eidolon/blob/master/sw.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_entry,node_engine,node_input_ui,node_presentation,node_service_worker toneBlue
class node_network,node_server,node_dispatch,node_protocol toneAmber
class node_world,node_combat,node_dungeons,node_progression toneMint
class node_social,node_economy,node_competition,node_casino,node_administration toneRose
class node_persistence,node_mongo,node_player toneIndigo
```

## Components

### Browser client

- [Client startup](https://github.com/aeml/eidolon/blob/master/src/main.js): `src/main.js`
- [Game engine](https://github.com/aeml/eidolon/blob/master/src/core/GameEngine.js): `src/core/GameEngine.js`
- [Input and UI](https://github.com/aeml/eidolon/blob/master/src/ui/UIManager.js): `src/ui/UIManager.js`
- [Rendering](https://github.com/aeml/eidolon/blob/master/src/core/RenderSystem.js): `src/core/RenderSystem.js`
- [Asset cache](https://github.com/aeml/eidolon/blob/master/sw.js): `sw.js`

### Realtime transport

- [Network manager](https://github.com/aeml/eidolon/blob/master/src/core/NetworkManager.js): `src/core/NetworkManager.js`
- [WebSocket server](https://github.com/aeml/eidolon/blob/master/server/main.go): `server/main.go`
- [Command dispatch](https://github.com/aeml/eidolon/blob/master/server/message_handlers.go): `server/message_handlers.go`
- [State protocol](https://github.com/aeml/eidolon/blob/master/proto/state.proto): `proto/state.proto`

### Game simulation

- [Authoritative world](https://github.com/aeml/eidolon/blob/master/server/internal/game/world.go): `server/internal/game/world.go`
- [Combat and abilities](https://github.com/aeml/eidolon/tree/master/server/internal/game): `server/internal/game`
- [Dungeons and raids](https://github.com/aeml/eidolon/tree/master/server/internal/game): `server/internal/game`
- [Quests and rewards](https://github.com/aeml/eidolon/tree/master/server/internal/game): `server/internal/game`

### Player systems

- [Party and guild](https://github.com/aeml/eidolon/tree/master/server/internal/game): `server/internal/game`
- [Items and trading](https://github.com/aeml/eidolon/tree/master/server/internal/game): `server/internal/game`
- [PvP and arenas](https://github.com/aeml/eidolon/tree/master/server/internal/game): `server/internal/game`
- [Casino games](https://github.com/aeml/eidolon/tree/master/server/internal/game): `server/internal/game`
- [Administration](https://github.com/aeml/eidolon/blob/master/server/admin_console_handlers.go): `server/admin_console_handlers.go`

### Persistent state

- [Persistence layer](https://github.com/aeml/eidolon/tree/master/server/internal/database): `server/internal/database`
- **MongoDB**

### Other components

- **Player**

## Connections

- Player → Client startup: starts game
- Client startup → Game engine: creates
- Input and UI → Game engine: submits intent
- Game engine → Network manager: sends commands
- Network manager → WebSocket server: WebSocket commands
- WebSocket server → Command dispatch: dispatches messages
- Command dispatch → Authoritative world: applies actions
- Authoritative world → Combat and abilities: simulates combat
- Authoritative world → Dungeons and raids: advances encounters
- Authoritative world → Quests and rewards: applies progression
- Authoritative world → Party and guild: handles social play
- Authoritative world → Items and trading: handles transactions
- Authoritative world → PvP and arenas: resolves PvP
- Authoritative world → Casino games: runs games
- WebSocket server → Administration: handles admin requests
- Authoritative world → Persistence layer: stores game data
- Persistence layer → MongoDB: reads and writes
- WebSocket server → Network manager: streams state
- Network manager → State protocol: decodes state
- Network manager → Game engine: updates state
- Game engine → Rendering: updates presentation
- Game engine → Input and UI: updates interface
- Client startup → Asset cache: registers cache