# nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler architecture

> Architecture diagram of the GitHub repository nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler
- Repository: https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler

## Overview

Echoes of the Crypt is a voice- and text-controlled dungeon crawler. The player speaks or types into the client; speech becomes a transcript, the interpreter produces a proposed command, and the deterministic game engine validates and executes it before the Phaser scene displays the result. The README documents optional server-side AI interpretation; the server also exposes command validation and preview. The graph preserves major UI, game-rule, persistence, and voice capabilities. Some connections are documented rather than verified in sampled implementation excerpts, so those edges are dashed.

Main entry points: [`apps/game-client/src/controller/GameController.ts`](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/controller/GameController.ts) (Game controller), [`apps/server/src/app.ts`](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/server/src/app.ts) (REST API), [`packages/ai-command-engine/src/pipeline.ts`](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/pipeline.ts) (Interpretation pipeline), [`packages/game-core/src/engine.ts`](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/engine.ts) (Game engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Game client"]
  node_app["App and menu<br/>[App.tsx]"]
  node_game_screen["Game screen<br/>[GameScreen.tsx]"]
  node_ui_panels["HUD and panels"]
  node_scene["Dungeon scene<br/>[DungeonScene.ts]"]
  node_controller["Game controller<br/>[GameController.ts]"]
  node_saves[("Save manager<br/>[saveManager.ts]")]
  node_settings[("Settings storage<br/>[settings.ts]")]
  node_voice_feedback["Voice feedback and sound<br/>[VoiceFeedback.ts]"]
end

subgraph group_voice["Voice and commands"]
  node_speech["Speech recognition"]
  node_transcript["Transcript processing"]
  node_interpreter["Command interpreter<br/>[interpreter.ts]"]
  node_pipeline["Interpretation pipeline<br/>[pipeline.ts]"]
  node_parser["Local parser<br/>[localParser.ts]"]
  node_normalizer["Text normalizer<br/>[normalize.ts]"]
  node_validator["Command validator<br/>[validator.ts]"]
  node_provider["LLM provider<br/>[providers.ts]"]
end

subgraph group_rules["Game rules"]
  node_engine["Game engine<br/>[engine.ts]"]
  node_grid["Grid and visibility<br/>[grid.ts]"]
  node_level["Level construction<br/>[level.ts]"]
  node_constants["Game definitions<br/>[constants.ts]"]
end

subgraph group_server["Server services"]
  node_api["REST API<br/>[app.ts]"]
  node_rate_limit["Rate limiter<br/>[rateLimit.ts]"]
  node_socket["Socket service<br/>[sockets.ts]"]
end

node_player(("Player"))

node_player -->|"starts game"| node_app
node_app -->|"starts or loads"| node_controller
node_app -->|"renders"| node_game_screen
node_game_screen -->|"renders"| node_ui_panels
node_player -.->|"speaks command"| node_speech
node_speech -->|"submits transcript"| node_controller
node_controller -.->|"processes text"| node_transcript
node_controller -->|"interprets command"| node_interpreter
node_interpreter -.->|"uses pipeline"| node_pipeline
node_pipeline -->|"parses locally"| node_parser
node_parser -->|"normalizes text"| node_normalizer
node_pipeline -->|"validates output"| node_validator
node_pipeline -->|"requests interpretation"| node_provider
node_controller -->|"executes command"| node_engine
node_engine -->|"uses grid rules"| node_grid
node_engine -->|"uses definitions"| node_constants
node_level -->|"uses grid helpers"| node_grid
node_controller -.->|"updates game view"| node_scene
node_controller -->|"loads and saves"| node_saves
node_controller -->|"loads and saves"| node_settings
node_controller -->|"plays feedback"| node_voice_feedback
node_api -->|"limits requests"| node_rate_limit
node_api -->|"interprets transcript"| node_pipeline
node_api -->|"validates command"| node_validator
node_api -->|"dry-runs command"| node_engine
node_player -.->|"requests server AI"| node_api
node_player -.->|"connects live"| node_socket

click node_app "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/App.tsx"
click node_game_screen "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/components/GameScreen.tsx"
click node_ui_panels "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/tree/main/apps/game-client/src/components"
click node_scene "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/game/DungeonScene.ts"
click node_controller "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/controller/GameController.ts"
click node_speech "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/voice/SpeechRecognitionManager.ts"
click node_transcript "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/voice/TranscriptProcessor.ts"
click node_interpreter "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/controller/interpreter.ts"
click node_pipeline "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/pipeline.ts"
click node_parser "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/localParser.ts"
click node_normalizer "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/normalize.ts"
click node_validator "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/validator.ts"
click node_provider "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/providers.ts"
click node_engine "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/engine.ts"
click node_grid "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/grid.ts"
click node_level "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/level.ts"
click node_constants "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/constants.ts"
click node_saves "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/persistence/saveManager.ts"
click node_settings "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/persistence/settings.ts"
click node_voice_feedback "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/voice/VoiceFeedback.ts"
click node_api "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/server/src/app.ts"
click node_rate_limit "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/server/src/rateLimit.ts"
click node_socket "https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/server/src/sockets.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_game_screen,node_ui_panels,node_scene,node_controller,node_saves,node_settings,node_voice_feedback toneBlue
class node_speech,node_transcript,node_interpreter,node_pipeline,node_parser,node_normalizer,node_validator,node_provider toneAmber
class node_engine,node_grid,node_level,node_constants toneMint
class node_api,node_rate_limit,node_socket toneRose
class node_player toneIndigo
```

## Components

### Game client

- [App and menu](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/App.tsx): `apps/game-client/src/App.tsx`
- [Game screen](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/components/GameScreen.tsx): `apps/game-client/src/components/GameScreen.tsx`
- [HUD and panels](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/tree/main/apps/game-client/src/components): `apps/game-client/src/components`
- [Dungeon scene](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/game/DungeonScene.ts): `apps/game-client/src/game/DungeonScene.ts`
- [Game controller](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/controller/GameController.ts): `apps/game-client/src/controller/GameController.ts`
- [Save manager](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/persistence/saveManager.ts): `apps/game-client/src/persistence/saveManager.ts`
- [Settings storage](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/persistence/settings.ts): `apps/game-client/src/persistence/settings.ts`
- [Voice feedback and sound](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/voice/VoiceFeedback.ts): `apps/game-client/src/voice/VoiceFeedback.ts`

### Voice and commands

- [Speech recognition](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/voice/SpeechRecognitionManager.ts): `apps/game-client/src/voice/SpeechRecognitionManager.ts`
- [Transcript processing](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/voice/TranscriptProcessor.ts): `apps/game-client/src/voice/TranscriptProcessor.ts`
- [Command interpreter](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/game-client/src/controller/interpreter.ts): `apps/game-client/src/controller/interpreter.ts`
- [Interpretation pipeline](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/pipeline.ts): `packages/ai-command-engine/src/pipeline.ts`
- [Local parser](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/localParser.ts): `packages/ai-command-engine/src/localParser.ts`
- [Text normalizer](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/normalize.ts): `packages/ai-command-engine/src/normalize.ts`
- [Command validator](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/validator.ts): `packages/ai-command-engine/src/validator.ts`
- [LLM provider](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/ai-command-engine/src/providers.ts): `packages/ai-command-engine/src/providers.ts`

### Game rules

- [Game engine](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/engine.ts): `packages/game-core/src/engine.ts`
- [Grid and visibility](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/grid.ts): `packages/game-core/src/grid.ts`
- [Level construction](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/level.ts): `packages/game-core/src/level.ts`
- [Game definitions](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/packages/game-core/src/constants.ts): `packages/game-core/src/constants.ts`

### Server services

- [REST API](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [Rate limiter](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/server/src/rateLimit.ts): `apps/server/src/rateLimit.ts`
- [Socket service](https://github.com/nikhil0074-dev/echoes-of-the-crypt-voice-controlled-ai-dungeon-crawler/blob/main/apps/server/src/sockets.ts): `apps/server/src/sockets.ts`

### Other components

- **Player**

## Connections

- Player → App and menu: starts game (evidence: `apps/game-client/src/App.tsx`)
- App and menu → Game controller: starts or loads (evidence: `apps/game-client/src/App.tsx`)
- App and menu → Game screen: renders (evidence: `apps/game-client/src/App.tsx`)
- Game screen → HUD and panels: renders (evidence: `apps/game-client/src/components/GameScreen.tsx`)
- Player → Speech recognition: speaks command (evidence: `README.md`)
- Speech recognition → Game controller: submits transcript (evidence: `apps/game-client/src/components/hooks.ts`)
- Game controller → Transcript processing: processes text (evidence: `apps/game-client/src/controller/GameController.ts`)
- Game controller → Command interpreter: interprets command (evidence: `apps/game-client/src/controller/GameController.ts`)
- Command interpreter → Interpretation pipeline: uses pipeline
- Interpretation pipeline → Local parser: parses locally (evidence: `packages/ai-command-engine/src/pipeline.ts`)
- Local parser → Text normalizer: normalizes text (evidence: `packages/ai-command-engine/src/localParser.ts`)
- Interpretation pipeline → Command validator: validates output (evidence: `packages/ai-command-engine/src/pipeline.ts`)
- Interpretation pipeline → LLM provider: requests interpretation (evidence: `packages/ai-command-engine/src/pipeline.ts`)
- Game controller → Game engine: executes command (evidence: `apps/game-client/src/controller/GameController.ts`)
- Game engine → Grid and visibility: uses grid rules (evidence: `packages/game-core/src/engine.ts`)
- Game engine → Game definitions: uses definitions (evidence: `packages/game-core/src/engine.ts`)
- Level construction → Grid and visibility: uses grid helpers (evidence: `packages/game-core/src/level.ts`)
- Game controller → Dungeon scene: updates game view (evidence: `apps/game-client/src/game/DungeonScene.ts`)
- Game controller → Save manager: loads and saves (evidence: `apps/game-client/src/controller/GameController.ts`)
- Game controller → Settings storage: loads and saves (evidence: `apps/game-client/src/controller/GameController.ts`)
- Game controller → Voice feedback and sound: plays feedback (evidence: `apps/game-client/src/controller/GameController.ts`)
- REST API → Rate limiter: limits requests (evidence: `apps/server/src/app.ts`)
- REST API → Interpretation pipeline: interprets transcript (evidence: `apps/server/src/app.ts`)
- REST API → Command validator: validates command (evidence: `apps/server/src/app.ts`)
- REST API → Game engine: dry-runs command (evidence: `apps/server/src/app.ts`)
- Player → REST API: requests server AI (evidence: `README.md`)
- Player → Socket service: connects live (evidence: `README.md`)