# julien6/assistcluedo architecture

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

- Interactive diagram: https://gitdiagram.com/julien6/assistcluedo
- Repository: https://github.com/julien6/assistcluedo

## Overview

AssistCluedo is a deterministic terminal investigation game and scenario-generation framework. Its central workflow starts with a CLI request, generates and validates a seeded mystery with a player-safe evidence package and quiz, then lets a player browse evidence, submit answers, and review the revealed solution. The graph also shows framework export and evaluation capabilities. The generation orchestration and key game interactions are evidenced by excerpts and the SOURCE INDEX; broader features such as audits and document regeneration are documented in the README, so some subsystem links rely on that documentation.

Main entry points: [`src/assistcluedo/game/tty.py`](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/tty.py) (TTY interface), [`src/assistcluedo/cli/main.py`](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/cli/main.py) (Command line), [`src/assistcluedo/framework/world.py`](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/world.py) (World generation), [`src/assistcluedo/game/evaluation.py`](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/evaluation.py) (Answer evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and game"]
  node_cli["Command line<br/>[main.py]"]
  node_terminal["TTY interface<br/>[tty.py]"]
end

subgraph group_generation["Scenario generation"]
  node_pack["Scenario pack<br/>[pack.yaml]"]
  node_pack_loader["Pack loader<br/>[pack.py]"]
  node_seed["Seed streams<br/>[seed.py]"]
  node_world["World generation<br/>[world.py]"]
  node_truth["Ground truth<br/>[scenario.py]"]
  node_timeline["Timeline and facts<br/>[timeline.py]"]
  node_traces["Evidence traces<br/>[traces.py]"]
  node_models["Scenario model<br/>[models.py]"]
  node_validator["Scenario validation<br/>[validation.py]"]
end

subgraph group_evidence["Evidence and exports"]
  node_doc_plans["Document planning<br/>[documents.py]"]
  node_doc_renderer["Document rendering<br/>[documents.py]"]
  node_textgen["Narrative generation<br/>[textgen.py]"]
  node_proof["Proof graph<br/>[proof.py]"]
  node_questions["Quiz generation<br/>[questions.py]"]
  node_export["Package export<br/>[export.py]"]
  node_player_package["Player package<br/>[player_package.py]"]
end

subgraph group_playback["Play and review"]
  node_sessions[("Game sessions<br/>[session.py]")]
  node_services["Game services<br/>[services.py]"]
  node_evaluation["Answer evaluation<br/>[evaluation.py]"]
  node_review["Solution review<br/>[review.py]"]
end

node_player(("Player"))

node_player -->|"issues commands"| node_cli
node_cli -->|"starts generation"| node_world
node_cli -->|"starts play"| node_terminal
node_world -->|"loads pack"| node_pack_loader
node_pack_loader -->|"reads data"| node_pack
node_world -->|"uses seeded randomness"| node_seed
node_world -->|"provides world"| node_truth
node_truth -->|"provides truth"| node_timeline
node_timeline -->|"provides facts and events"| node_traces
node_traces -->|"provides traces"| node_doc_plans
node_doc_plans -->|"provides plans"| node_doc_renderer
node_doc_renderer -->|"generates prose"| node_textgen
node_doc_renderer -->|"provides documents"| node_proof
node_proof -->|"provides proof links"| node_questions
node_questions -->|"quiz enters scenario"| node_validator
node_validator -->|"validates before export"| node_export
node_export -->|"builds player view"| node_player_package
node_export -->|"serializes scenario"| node_models
node_player_package -.->|"supplies player content"| node_terminal
node_terminal -->|"uses game services"| node_services
node_terminal -->|"loads and saves"| node_sessions
node_services -->|"manages session"| node_sessions
node_services -->|"evaluates answers"| node_evaluation
node_terminal -.->|"submits answers"| node_evaluation
node_cli -->|"runs evaluation"| node_evaluation
node_cli -->|"runs review"| node_review
node_review -->|"uses result details"| node_evaluation
node_player -->|"browses and answers"| node_terminal

click node_cli "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/cli/main.py"
click node_terminal "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/tty.py"
click node_pack "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/scenario_packs/classic_manor/pack.yaml"
click node_pack_loader "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/pack.py"
click node_seed "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/seed.py"
click node_world "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/world.py"
click node_truth "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/scenario.py"
click node_timeline "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/timeline.py"
click node_traces "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/traces.py"
click node_doc_plans "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/documents.py"
click node_doc_renderer "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/documents.py"
click node_textgen "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/textgen.py"
click node_proof "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/proof.py"
click node_questions "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/questions.py"
click node_models "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/models.py"
click node_validator "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/validation.py"
click node_export "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/export.py"
click node_player_package "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/player_package.py"
click node_sessions "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/session.py"
click node_services "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/services.py"
click node_evaluation "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/evaluation.py"
click node_review "https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/review.py"

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_cli,node_terminal toneBlue
class node_pack,node_pack_loader,node_seed,node_world,node_truth,node_timeline,node_traces,node_models,node_validator toneAmber
class node_doc_plans,node_doc_renderer,node_textgen,node_proof,node_questions,node_export,node_player_package toneMint
class node_sessions,node_services,node_evaluation,node_review toneRose
class node_player toneIndigo
```

## Components

### CLI and game

- [Command line](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/cli/main.py): `src/assistcluedo/cli/main.py`
- [TTY interface](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/tty.py): `src/assistcluedo/game/tty.py`

### Scenario generation

- [Scenario pack](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/scenario_packs/classic_manor/pack.yaml): `src/assistcluedo/scenario_packs/classic_manor/pack.yaml`
- [Pack loader](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/pack.py): `src/assistcluedo/framework/pack.py`
- [Seed streams](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/seed.py): `src/assistcluedo/framework/seed.py`
- [World generation](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/world.py): `src/assistcluedo/framework/world.py`
- [Ground truth](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/scenario.py): `src/assistcluedo/framework/scenario.py`
- [Timeline and facts](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/timeline.py): `src/assistcluedo/framework/timeline.py`
- [Evidence traces](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/traces.py): `src/assistcluedo/framework/traces.py`
- [Scenario model](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/models.py): `src/assistcluedo/framework/models.py`
- [Scenario validation](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/validation.py): `src/assistcluedo/framework/validation.py`

### Evidence and exports

- [Document planning](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/documents.py): `src/assistcluedo/framework/documents.py`
- [Document rendering](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/documents.py): `src/assistcluedo/framework/documents.py`
- [Narrative generation](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/textgen.py): `src/assistcluedo/framework/textgen.py`
- [Proof graph](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/proof.py): `src/assistcluedo/framework/proof.py`
- [Quiz generation](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/questions.py): `src/assistcluedo/framework/questions.py`
- [Package export](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/framework/export.py): `src/assistcluedo/framework/export.py`
- [Player package](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/player_package.py): `src/assistcluedo/game/player_package.py`

### Play and review

- [Game sessions](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/session.py): `src/assistcluedo/game/session.py`
- [Game services](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/services.py): `src/assistcluedo/game/services.py`
- [Answer evaluation](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/evaluation.py): `src/assistcluedo/game/evaluation.py`
- [Solution review](https://github.com/julien6/assistcluedo/blob/main/src/assistcluedo/game/review.py): `src/assistcluedo/game/review.py`

### Other components

- **Player**

## Connections

- Player → Command line: issues commands (evidence: `README.md`)
- Command line → World generation: starts generation (evidence: `src/assistcluedo/cli/main.py`)
- Command line → TTY interface: starts play (evidence: `src/assistcluedo/cli/main.py`)
- World generation → Pack loader: loads pack (evidence: `src/assistcluedo/framework/world.py`)
- Pack loader → Scenario pack: reads data (evidence: `src/assistcluedo/framework/pack.py`)
- World generation → Seed streams: uses seeded randomness (evidence: `src/assistcluedo/framework/world.py`)
- World generation → Ground truth: provides world (evidence: `src/assistcluedo/framework/generator.py`)
- Ground truth → Timeline and facts: provides truth (evidence: `src/assistcluedo/framework/generator.py`)
- Timeline and facts → Evidence traces: provides facts and events (evidence: `src/assistcluedo/framework/generator.py`)
- Evidence traces → Document planning: provides traces (evidence: `src/assistcluedo/framework/generator.py`)
- Document planning → Document rendering: provides plans (evidence: `src/assistcluedo/framework/generator.py`)
- Document rendering → Narrative generation: generates prose (evidence: `src/assistcluedo/framework/documents.py`)
- Document rendering → Proof graph: provides documents (evidence: `src/assistcluedo/framework/generator.py`)
- Proof graph → Quiz generation: provides proof links (evidence: `src/assistcluedo/framework/generator.py`)
- Quiz generation → Scenario validation: quiz enters scenario (evidence: `src/assistcluedo/framework/generator.py`)
- Scenario validation → Package export: validates before export (evidence: `src/assistcluedo/framework/export.py`)
- Package export → Player package: builds player view (evidence: `src/assistcluedo/framework/export.py`)
- Package export → Scenario model: serializes scenario (evidence: `src/assistcluedo/framework/export.py`)
- Player package → TTY interface: supplies player content (evidence: `README.md`)
- TTY interface → Game services: uses game services (evidence: `src/assistcluedo/game/tty.py`)
- TTY interface → Game sessions: loads and saves (evidence: `src/assistcluedo/game/tty.py`)
- Game services → Game sessions: manages session (evidence: `src/assistcluedo/game/services.py`)
- Game services → Answer evaluation: evaluates answers (evidence: `src/assistcluedo/game/services.py`)
- TTY interface → Answer evaluation: submits answers (evidence: `README.md`)
- Command line → Answer evaluation: runs evaluation (evidence: `src/assistcluedo/cli/main.py`)
- Command line → Solution review: runs review (evidence: `src/assistcluedo/cli/main.py`)
- Solution review → Answer evaluation: uses result details (evidence: `src/assistcluedo/game/review.py`)
- Player → TTY interface: browses and answers (evidence: `README.md`)
