# donsmackzy/lugbe-to-maitama architecture

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

- Interactive diagram: https://gitdiagram.com/donsmackzy/lugbe-to-maitama
- Repository: https://github.com/donsmackzy/lugbe-to-maitama

## Overview

Lugbe to Maitama is a browser-based multiplayer Abuja survival game. Players accept the satire disclaimer, connect from the browser, and send intents to an authoritative Colyseus room; the room resolves simulation effects, persists economic changes, and syncs state back for client reconciliation and HUD rendering. The README documents additional simulation, Redis recovery/rate limiting, and optional AI dialogue capabilities. Some links reflect README documentation because sampled excerpts do not expose all runtime calls.

Main entry points: [`apps/server/src/rooms/WorldRoom.ts`](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/rooms/WorldRoom.ts) (World room), [`apps/web/src/main.ts`](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/main.ts) (Client bootstrap), [`apps/web/src/game/MainScene.ts`](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/game/MainScene.ts) (Isometric scene), [`apps/web/src/network/ColyseusClient.ts`](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/network/ColyseusClient.ts) (Colyseus client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser game"]
  node_splash["Disclaimer onboarding<br/>[SplashScreen.ts]"]
  node_webentry["Client bootstrap<br/>[main.ts]"]
  node_scene["Isometric scene<br/>[MainScene.ts]"]
  node_prediction["Movement prediction"]
  node_network["Colyseus client<br/>[ColyseusClient.ts]"]
  node_hud["Game HUD<br/>[GameHUD.ts]"]
end

subgraph group_server["Authoritative game"]
  node_room["World room<br/>[WorldRoom.ts]"]
  node_roomstate["Room state schema<br/>[WorldRoomState.ts]"]
  node_serial["Player serial queue<br/>[PlayerSerial.ts]"]
  node_ledger["Economic ledger<br/>[ledger.ts]"]
  node_redis[("Redis services<br/>[redis.ts]")]
end

subgraph group_engine["Simulation engine"]
  node_engine["Intent resolution<br/>[resolve.ts]"]
  node_effects["Effect model<br/>[effects.ts]"]
  node_evaluator["Rule evaluator<br/>[evaluator.ts]"]
  node_state["Simulation state<br/>[state.ts]"]
  node_advance["World advancement<br/>[advance.ts]"]
  node_movement["Movement rules<br/>[movement.ts]"]
  node_market["Market rules<br/>[market.ts]"]
  node_nav["Navigation grid<br/>[nav-grid.ts]"]
  node_simulation["Simulation helpers<br/>[simulation.ts]"]
  node_citypack["Abuja city pack"]
end

subgraph group_ai["NPC dialogue"]
  node_aihttp["Dialogue HTTP service<br/>[server.ts]"]
  node_stampede["Request deduplicator<br/>[stampede.ts]"]
  node_aicache[("Dialogue cache<br/>[redis.ts]")]
  node_llm["LLM client<br/>[client.ts]"]
  node_prompts["Prompt construction<br/>[prompts.ts]"]
end

node_player(("Player"))
node_postgres[("PostgreSQL")]
node_redisservice[("Redis")]
node_openai["OpenAI API"]

node_player -->|"accepts disclaimer"| node_splash
node_splash -->|"provides credentials"| node_webentry
node_webentry -->|"creates"| node_hud
node_webentry -->|"connects"| node_network
node_webentry -->|"starts"| node_scene
node_scene -->|"uses"| node_prediction
node_scene -->|"dispatches intents"| node_network
node_scene -->|"updates"| node_hud
node_network -->|"sends intents"| node_room
node_room -->|"syncs state and ACKs"| node_network
node_room -->|"uses schema"| node_roomstate
node_room -->|"queues player work"| node_serial
node_serial -->|"runs intent resolution"| node_engine
node_room -->|"commits effects"| node_ledger
node_room -->|"checks limits and snapshots"| node_redis
node_ledger -->|"writes transactions"| node_postgres
node_redis -->|"stores snapshots and limits"| node_redisservice
node_engine -->|"evaluates rules"| node_evaluator
node_evaluator -->|"produces effects"| node_effects
node_engine -->|"reads world state"| node_state
node_advance -->|"evaluates ticks"| node_evaluator
node_advance -->|"produces effects"| node_effects
node_state -->|"uses grid"| node_nav
node_simulation -->|"uses movement rules"| node_movement
node_simulation -->|"uses market rules"| node_market
node_room -->|"loads rules and data"| node_citypack
node_room -.->|"requests dialogue"| node_aihttp
node_aihttp -->|"checks and stores cache"| node_aicache
node_aihttp -->|"coalesces cache misses"| node_stampede
node_stampede -->|"runs single flight"| node_llm
node_aicache -->|"reads and writes"| node_redisservice
node_llm -->|"builds prompt"| node_prompts
node_llm -->|"requests completion"| node_openai

click node_splash "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/ui/SplashScreen.ts"
click node_webentry "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/main.ts"
click node_scene "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/game/MainScene.ts"
click node_prediction "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/game/PredictionManager.ts"
click node_network "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/network/ColyseusClient.ts"
click node_hud "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/ui/GameHUD.ts"
click node_room "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/rooms/WorldRoom.ts"
click node_roomstate "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/rooms/schema/WorldRoomState.ts"
click node_serial "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/concurrency/PlayerSerial.ts"
click node_ledger "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/economy/ledger.ts"
click node_redis "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/storage/redis.ts"
click node_engine "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/resolve.ts"
click node_effects "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/effects.ts"
click node_evaluator "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/rules/evaluator.ts"
click node_state "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/state.ts"
click node_advance "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/advance.ts"
click node_movement "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/movement.ts"
click node_market "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/market.ts"
click node_nav "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/nav-grid.ts"
click node_simulation "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/simulation.ts"
click node_citypack "https://github.com/donsmackzy/lugbe-to-maitama/tree/main/city-packs/abuja"
click node_aihttp "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/server.ts"
click node_stampede "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/cache/stampede.ts"
click node_aicache "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/storage/redis.ts"
click node_llm "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/llm/client.ts"
click node_prompts "https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/llm/prompts.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_splash,node_webentry,node_scene,node_prediction,node_network,node_hud toneBlue
class node_room,node_roomstate,node_serial,node_ledger,node_redis,node_postgres,node_redisservice toneAmber
class node_engine,node_effects,node_evaluator,node_state,node_advance,node_movement,node_market,node_nav,node_simulation,node_citypack,node_openai toneMint
class node_aihttp,node_stampede,node_aicache,node_llm,node_prompts toneRose
class node_player toneIndigo
```

## Components

### Browser game

- [Disclaimer onboarding](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/ui/SplashScreen.ts): `apps/web/src/ui/SplashScreen.ts`
- [Client bootstrap](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/main.ts): `apps/web/src/main.ts`
- [Isometric scene](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/game/MainScene.ts): `apps/web/src/game/MainScene.ts`
- [Movement prediction](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/game/PredictionManager.ts): `apps/web/src/game/PredictionManager.ts`
- [Colyseus client](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/network/ColyseusClient.ts): `apps/web/src/network/ColyseusClient.ts`
- [Game HUD](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/web/src/ui/GameHUD.ts): `apps/web/src/ui/GameHUD.ts`

### Authoritative game

- [World room](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/rooms/WorldRoom.ts): `apps/server/src/rooms/WorldRoom.ts`
- [Room state schema](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/rooms/schema/WorldRoomState.ts): `apps/server/src/rooms/schema/WorldRoomState.ts`
- [Player serial queue](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/concurrency/PlayerSerial.ts): `apps/server/src/concurrency/PlayerSerial.ts`
- [Economic ledger](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/economy/ledger.ts): `apps/server/src/economy/ledger.ts`
- [Redis services](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/server/src/storage/redis.ts): `apps/server/src/storage/redis.ts`

### Simulation engine

- [Intent resolution](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/resolve.ts): `packages/engine/src/resolve.ts`
- [Effect model](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/effects.ts): `packages/engine/src/effects.ts`
- [Rule evaluator](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/rules/evaluator.ts): `packages/engine/src/rules/evaluator.ts`
- [Simulation state](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/state.ts): `packages/engine/src/state.ts`
- [World advancement](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/advance.ts): `packages/engine/src/advance.ts`
- [Movement rules](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/movement.ts): `packages/engine/src/movement.ts`
- [Market rules](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/market.ts): `packages/engine/src/market.ts`
- [Navigation grid](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/nav-grid.ts): `packages/engine/src/nav-grid.ts`
- [Simulation helpers](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/packages/engine/src/simulation.ts): `packages/engine/src/simulation.ts`
- [Abuja city pack](https://github.com/donsmackzy/lugbe-to-maitama/tree/main/city-packs/abuja): `city-packs/abuja`

### NPC dialogue

- [Dialogue HTTP service](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/server.ts): `apps/ai-service/src/server.ts`
- [Request deduplicator](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/cache/stampede.ts): `apps/ai-service/src/cache/stampede.ts`
- [Dialogue cache](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/storage/redis.ts): `apps/ai-service/src/storage/redis.ts`
- [LLM client](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/llm/client.ts): `apps/ai-service/src/llm/client.ts`
- [Prompt construction](https://github.com/donsmackzy/lugbe-to-maitama/blob/main/apps/ai-service/src/llm/prompts.ts): `apps/ai-service/src/llm/prompts.ts`

### Other components

- **Player**
- **PostgreSQL**
- **Redis**
- **OpenAI API**

## Connections

- Player → Disclaimer onboarding: accepts disclaimer
- Disclaimer onboarding → Client bootstrap: provides credentials (evidence: `apps/web/src/main.ts`)
- Client bootstrap → Game HUD: creates (evidence: `apps/web/src/main.ts`)
- Client bootstrap → Colyseus client: connects (evidence: `apps/web/src/main.ts`)
- Client bootstrap → Isometric scene: starts (evidence: `apps/web/src/main.ts`)
- Isometric scene → Movement prediction: uses (evidence: `apps/web/src/game/MainScene.ts`)
- Isometric scene → Colyseus client: dispatches intents (evidence: `apps/web/src/game/MainScene.ts`)
- Isometric scene → Game HUD: updates (evidence: `apps/web/src/game/MainScene.ts`)
- Colyseus client → World room: sends intents (evidence: `README.md`)
- World room → Colyseus client: syncs state and ACKs (evidence: `README.md`)
- World room → Room state schema: uses schema (evidence: `apps/server/src/rooms/WorldRoom.ts`)
- World room → Player serial queue: queues player work (evidence: `apps/server/src/rooms/WorldRoom.ts`)
- Player serial queue → Intent resolution: runs intent resolution (evidence: `README.md`)
- World room → Economic ledger: commits effects (evidence: `apps/server/src/rooms/WorldRoom.ts`)
- World room → Redis services: checks limits and snapshots (evidence: `apps/server/src/rooms/WorldRoom.ts`)
- Economic ledger → PostgreSQL: writes transactions (evidence: `apps/server/src/economy/ledger.ts`)
- Redis services → Redis: stores snapshots and limits (evidence: `README.md`)
- Intent resolution → Rule evaluator: evaluates rules (evidence: `packages/engine/src/resolve.ts`)
- Rule evaluator → Effect model: produces effects (evidence: `packages/engine/src/rules/evaluator.ts`)
- Intent resolution → Simulation state: reads world state (evidence: `packages/engine/src/resolve.ts`)
- World advancement → Rule evaluator: evaluates ticks (evidence: `packages/engine/src/advance.ts`)
- World advancement → Effect model: produces effects (evidence: `packages/engine/src/advance.ts`)
- Simulation state → Navigation grid: uses grid (evidence: `packages/engine/src/state.ts`)
- Simulation helpers → Movement rules: uses movement rules (evidence: `packages/engine/src/simulation.ts`)
- Simulation helpers → Market rules: uses market rules (evidence: `packages/engine/src/simulation.ts`)
- World room → Abuja city pack: loads rules and data (evidence: `apps/server/src/rooms/WorldRoom.ts`)
- World room → Dialogue HTTP service: requests dialogue (evidence: `README.md`)
- Dialogue HTTP service → Dialogue cache: checks and stores cache (evidence: `apps/ai-service/src/server.ts`)
- Dialogue HTTP service → Request deduplicator: coalesces cache misses (evidence: `apps/ai-service/src/server.ts`)
- Request deduplicator → LLM client: runs single flight (evidence: `README.md`)
- Dialogue cache → Redis: reads and writes (evidence: `README.md`)
- LLM client → Prompt construction: builds prompt (evidence: `apps/ai-service/src/llm/client.ts`)
- LLM client → OpenAI API: requests completion (evidence: `apps/ai-service/src/llm/client.ts`)
