# acm-projects/agentic-detective architecture

> Architecture diagram of the GitHub repository acm-projects/agentic-detective, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/acm-projects/agentic-detective
- Repository: https://github.com/acm-projects/agentic-detective

## Overview

Agentic Detective is a browser-based mystery game: players configure a case, investigate suspects through natural-language interrogation, collect clues, and make a final accusation under a timer. Its runtime separates case generation and game state from routed screens, clue/notification mechanics, and voice services. The README also describes stress, voice input, shared suspect portraits, save/community features, and minigames. Some of those branches are documented or indexed but their implementation details were not sampled, so their connections are limited to supported evidence.

Main entry points: [`src/useGameStore.ts`](https://github.com/acm-projects/agentic-detective/blob/main/src/useGameStore.ts) (Game state), [`src/App.tsx`](https://github.com/acm-projects/agentic-detective/blob/main/src/App.tsx) (Route shell), [`src/Interrogate.tsx`](https://github.com/acm-projects/agentic-detective/blob/main/src/Interrogate.tsx) (Suspect interviews), [`src/NewGame.tsx`](https://github.com/acm-projects/agentic-detective/blob/main/src/NewGame.tsx) (New case setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Game experience"]
  node_app["Route shell<br/>[App.tsx]"]
  node_newgame["New case setup<br/>[NewGame.tsx]"]
  node_loading["Case loading<br/>[LoadingScreen.tsx]"]
  node_desk["Investigation desk<br/>[DeskMessage.tsx]"]
  node_interrogate["Suspect interviews<br/>[Interrogate.tsx]"]
  node_accuse["Final accusation<br/>[Accuse.tsx]"]
  node_report["Case report"]
  node_suspects["Suspect roster<br/>[Suspects.tsx]"]
  node_community["Shared cases<br/>[Community.tsx]"]
end

subgraph group_mystery["Mystery and state"]
  node_store["Game state<br/>[useGameStore.ts]"]
  node_casefile["Case generation<br/>[caseFile.ts]"]
  node_portrait["Portrait renderer"]
end

subgraph group_evidence["Evidence and tools"]
  node_cluebook["Clue book<br/>[ClueBook.tsx]"]
  node_notifications["Clue scheduler state"]
  node_scheduler["Notification scheduler"]
  node_minigames["Clue minigames"]
  node_savedgames["Saved games<br/>[SavedGamesList.tsx]"]
end

subgraph group_services["AI and voice"]
  node_ai["Model service<br/>[ai.ts]"]
  node_tts["Speech synthesis<br/>[ttsService.ts]"]
  node_speech["Voice input<br/>[speechToText.ts]"]
end

node_player(("Player"))
node_elevenlabs["ElevenLabs"]
node_model["LLM provider"]

node_player -->|"plays"| node_app
node_app -->|"routes to"| node_newgame
node_app -->|"routes to"| node_loading
node_app -->|"routes to"| node_desk
node_app -->|"routes to"| node_interrogate
node_app -->|"routes to"| node_accuse
node_app -->|"routes to"| node_report
node_app -->|"routes to"| node_cluebook
node_app -->|"routes to"| node_suspects
node_newgame -->|"sets up"| node_store
node_newgame -->|"shows saves"| node_savedgames
node_newgame -->|"offers sharing"| node_community
node_loading -->|"continues to"| node_newgame
node_store -->|"generates case"| node_casefile
node_casefile -->|"calls model"| node_ai
node_ai -.->|"requests completion"| node_model
node_store -->|"calls for replies"| node_ai
node_store -.->|"requests speech"| node_tts
node_tts -->|"streams audio"| node_elevenlabs
node_interrogate -->|"reads and updates"| node_store
node_interrogate -->|"captures questions"| node_speech
node_interrogate -->|"renders suspect"| node_portrait
node_interrogate -->|"drives schedule"| node_scheduler
node_scheduler -->|"ticks and purges"| node_notifications
node_cluebook -->|"reads case state"| node_store
node_cluebook -->|"reads clues"| node_notifications
node_notifications -->|"posts progress"| node_store
node_notifications -->|"opens games"| node_minigames
node_accuse -->|"submits accusation"| node_store
node_report -->|"reads case result"| node_store
node_suspects -->|"reads suspects"| node_store

click node_app "https://github.com/acm-projects/agentic-detective/blob/main/src/App.tsx"
click node_newgame "https://github.com/acm-projects/agentic-detective/blob/main/src/NewGame.tsx"
click node_loading "https://github.com/acm-projects/agentic-detective/blob/main/src/LoadingScreen.tsx"
click node_desk "https://github.com/acm-projects/agentic-detective/blob/main/src/desk/DeskMessage.tsx"
click node_interrogate "https://github.com/acm-projects/agentic-detective/blob/main/src/Interrogate.tsx"
click node_accuse "https://github.com/acm-projects/agentic-detective/blob/main/src/Accuse.tsx"
click node_report "https://github.com/acm-projects/agentic-detective/blob/main/src/CaseReportScreen.tsx"
click node_suspects "https://github.com/acm-projects/agentic-detective/blob/main/src/Suspects.tsx"
click node_community "https://github.com/acm-projects/agentic-detective/blob/main/src/Community.tsx"
click node_store "https://github.com/acm-projects/agentic-detective/blob/main/src/useGameStore.ts"
click node_casefile "https://github.com/acm-projects/agentic-detective/blob/main/src/caseFile.ts"
click node_portrait "https://github.com/acm-projects/agentic-detective/blob/main/src/components/SuspectPortrait.tsx"
click node_cluebook "https://github.com/acm-projects/agentic-detective/blob/main/src/ClueBook.tsx"
click node_notifications "https://github.com/acm-projects/agentic-detective/blob/main/src/store/useNotificationStore.ts"
click node_scheduler "https://github.com/acm-projects/agentic-detective/blob/main/src/services/useNotificationScheduler.ts"
click node_minigames "https://github.com/acm-projects/agentic-detective/tree/main/src/components/minigames"
click node_savedgames "https://github.com/acm-projects/agentic-detective/blob/main/src/components/savegamelist/SavedGamesList.tsx"
click node_ai "https://github.com/acm-projects/agentic-detective/blob/main/src/services/ai.ts"
click node_tts "https://github.com/acm-projects/agentic-detective/blob/main/src/services/ttsService.ts"
click node_speech "https://github.com/acm-projects/agentic-detective/blob/main/src/services/speechToText.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_newgame,node_loading,node_desk,node_interrogate,node_accuse,node_report,node_suspects,node_community toneBlue
class node_store,node_casefile,node_portrait toneAmber
class node_cluebook,node_notifications,node_scheduler,node_minigames,node_savedgames toneMint
class node_ai,node_tts,node_speech toneRose
class node_player,node_elevenlabs,node_model toneIndigo
```

## Components

### Game experience

- [Route shell](https://github.com/acm-projects/agentic-detective/blob/main/src/App.tsx): `src/App.tsx`
- [New case setup](https://github.com/acm-projects/agentic-detective/blob/main/src/NewGame.tsx): `src/NewGame.tsx`
- [Case loading](https://github.com/acm-projects/agentic-detective/blob/main/src/LoadingScreen.tsx): `src/LoadingScreen.tsx`
- [Investigation desk](https://github.com/acm-projects/agentic-detective/blob/main/src/desk/DeskMessage.tsx): `src/desk/DeskMessage.tsx`
- [Suspect interviews](https://github.com/acm-projects/agentic-detective/blob/main/src/Interrogate.tsx): `src/Interrogate.tsx`
- [Final accusation](https://github.com/acm-projects/agentic-detective/blob/main/src/Accuse.tsx): `src/Accuse.tsx`
- [Case report](https://github.com/acm-projects/agentic-detective/blob/main/src/CaseReportScreen.tsx): `src/CaseReportScreen.tsx`
- [Suspect roster](https://github.com/acm-projects/agentic-detective/blob/main/src/Suspects.tsx): `src/Suspects.tsx`
- [Shared cases](https://github.com/acm-projects/agentic-detective/blob/main/src/Community.tsx): `src/Community.tsx`

### Mystery and state

- [Game state](https://github.com/acm-projects/agentic-detective/blob/main/src/useGameStore.ts): `src/useGameStore.ts`
- [Case generation](https://github.com/acm-projects/agentic-detective/blob/main/src/caseFile.ts): `src/caseFile.ts`
- [Portrait renderer](https://github.com/acm-projects/agentic-detective/blob/main/src/components/SuspectPortrait.tsx): `src/components/SuspectPortrait.tsx`

### Evidence and tools

- [Clue book](https://github.com/acm-projects/agentic-detective/blob/main/src/ClueBook.tsx): `src/ClueBook.tsx`
- [Clue scheduler state](https://github.com/acm-projects/agentic-detective/blob/main/src/store/useNotificationStore.ts): `src/store/useNotificationStore.ts`
- [Notification scheduler](https://github.com/acm-projects/agentic-detective/blob/main/src/services/useNotificationScheduler.ts): `src/services/useNotificationScheduler.ts`
- [Clue minigames](https://github.com/acm-projects/agentic-detective/tree/main/src/components/minigames): `src/components/minigames`
- [Saved games](https://github.com/acm-projects/agentic-detective/blob/main/src/components/savegamelist/SavedGamesList.tsx): `src/components/savegamelist/SavedGamesList.tsx`

### AI and voice

- [Model service](https://github.com/acm-projects/agentic-detective/blob/main/src/services/ai.ts): `src/services/ai.ts`
- [Speech synthesis](https://github.com/acm-projects/agentic-detective/blob/main/src/services/ttsService.ts): `src/services/ttsService.ts`
- [Voice input](https://github.com/acm-projects/agentic-detective/blob/main/src/services/speechToText.ts): `src/services/speechToText.ts`

### Other components

- **Player**
- **ElevenLabs**
- **LLM provider**

## Connections

- Player → Route shell: plays
- Route shell → New case setup: routes to (evidence: `src/App.tsx`)
- Route shell → Case loading: routes to (evidence: `src/App.tsx`)
- Route shell → Investigation desk: routes to (evidence: `src/App.tsx`)
- Route shell → Suspect interviews: routes to (evidence: `src/App.tsx`)
- Route shell → Final accusation: routes to (evidence: `src/App.tsx`)
- Route shell → Case report: routes to (evidence: `src/App.tsx`)
- Route shell → Clue book: routes to (evidence: `src/App.tsx`)
- Route shell → Suspect roster: routes to (evidence: `src/App.tsx`)
- New case setup → Game state: sets up (evidence: `src/NewGame.tsx`)
- New case setup → Saved games: shows saves (evidence: `src/NewGame.tsx`)
- New case setup → Shared cases: offers sharing (evidence: `src/NewGame.tsx`)
- Case loading → New case setup: continues to (evidence: `src/LoadingScreen.tsx`)
- Game state → Case generation: generates case (evidence: `src/useGameStore.ts`)
- Case generation → Model service: calls model (evidence: `src/caseFile.ts`)
- Model service → LLM provider: requests completion
- Game state → Model service: calls for replies (evidence: `src/useGameStore.ts`)
- Game state → Speech synthesis: requests speech (evidence: `src/useGameStore.ts`)
- Speech synthesis → ElevenLabs: streams audio (evidence: `src/services/ttsService.ts`)
- Suspect interviews → Game state: reads and updates (evidence: `src/Interrogate.tsx`)
- Suspect interviews → Voice input: captures questions (evidence: `src/Interrogate.tsx`)
- Suspect interviews → Portrait renderer: renders suspect (evidence: `src/Interrogate.tsx`)
- Suspect interviews → Notification scheduler: drives schedule (evidence: `src/Interrogate.tsx`)
- Notification scheduler → Clue scheduler state: ticks and purges (evidence: `src/services/useNotificationScheduler.ts`)
- Clue book → Game state: reads case state (evidence: `src/ClueBook.tsx`)
- Clue book → Clue scheduler state: reads clues (evidence: `src/ClueBook.tsx`)
- Clue scheduler state → Game state: posts progress (evidence: `src/store/useNotificationStore.ts`)
- Clue scheduler state → Clue minigames: opens games (evidence: `src/components/minigames/MinigameModal.tsx`)
- Final accusation → Game state: submits accusation (evidence: `src/Accuse.tsx`)
- Case report → Game state: reads case result (evidence: `src/CaseReportScreen.tsx`)
- Suspect roster → Game state: reads suspects (evidence: `src/Suspects.tsx`)
