# mhdsahil1/who_knows architecture

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

- Interactive diagram: https://gitdiagram.com/mhdsahil1/who_knows
- Repository: https://github.com/mhdsahil1/who_knows

## Overview

Who Knows! is a local, pass-and-play social deduction game: one group configures a game, privately passes a device for role reveals, discusses face-to-face, votes, and sees the result. The graph preserves the documented Classic and One-Shot flows, configurable Imposters, Chaos Mode, Final Guess, built-in and custom words, and Associated Words. Paths for screens and managers are supported by the tree; detailed call wiring was not sampled, so the graph uses documented workflow links and avoids asserting internal calls between game helpers.

Main entry points: [`lib/screens/vote_result_screen.dart`](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/vote_result_screen.dart) (Vote results), [`lib/screens/role_reveal_screen.dart`](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/role_reveal_screen.dart) (Role reveal), [`lib/screens/voting_screen.dart`](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/voting_screen.dart) (Voting), [`lib/screens/category_selection_screen.dart`](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/category_selection_screen.dart) (Word selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Game experience"]
  node_entry["App entry<br/>[main.dart]"]
  node_app["App shell<br/>[app.dart]"]
  node_home["Home<br/>[home_screen.dart]"]
  node_player_setup["Player setup"]
  node_mode_setup["Mode setup"]
  node_game_config["Game configuration"]
  node_ready["Ready screen<br/>[ready_screen.dart]"]
  node_role_reveal["Role reveal"]
  node_discussion["Discussion"]
  node_voting["Voting<br/>[voting_screen.dart]"]
  node_vote_results["Vote results"]
  node_final_guess["Final guess"]
  node_game_over["Game result"]
end

subgraph group_rules["Game rules"]
  node_engine["Game engine<br/>[game_engine.dart]"]
  node_roles["Role assignment<br/>[role_manager.dart]"]
  node_vote_rules["Vote rules<br/>[vote_manager.dart]"]
  node_win_rules["Win conditions<br/>[win_condition.dart]"]
end

subgraph group_words["Word systems"]
  node_category_setup["Word selection"]
  node_word_rules["Word selection logic<br/>[word_manager.dart]"]
  node_word_database[("Built-in words<br/>[word_database.dart]")]
  node_custom_words["Custom words"]
  node_associated_words["Associated Words"]
  node_associated_service["Association service"]
end

subgraph group_local_data["Local data"]
  node_custom_service["Custom word service"]
  node_storage[("Local storage")]
end

node_players(("Player group"))

node_players -->|"launches"| node_entry
node_entry -->|"starts"| node_app
node_app -->|"opens"| node_home
node_home -->|"starts game"| node_player_setup
node_player_setup -->|"continues setup"| node_mode_setup
node_mode_setup -->|"selects mode"| node_game_config
node_game_config -->|"sets options"| node_category_setup
node_category_setup -->|"confirms words"| node_ready
node_ready -->|"begins round"| node_role_reveal
node_role_reveal -->|"reveals roles"| node_discussion
node_discussion -->|"opens vote"| node_voting
node_voting -->|"submits vote"| node_vote_results
node_vote_results -->|"checks outcome"| node_win_rules
node_vote_results -->|"caught Imposter"| node_final_guess
node_final_guess -->|"checks guess"| node_win_rules
node_win_rules -->|"determines result"| node_game_over
node_vote_results -->|"starts next round"| node_ready
node_role_reveal -->|"role assignment stage"| node_roles
node_voting -->|"vote stage"| node_vote_rules
node_category_setup -->|"chooses words"| node_word_rules
node_word_rules -->|"reads categories"| node_word_database
node_custom_words -->|"manages words"| node_custom_service
node_custom_service -->|"persists locally"| node_storage
node_associated_words -->|"requests associations"| node_associated_service

click node_entry "https://github.com/mhdsahil1/who_knows/blob/main/lib/main.dart"
click node_app "https://github.com/mhdsahil1/who_knows/blob/main/lib/app.dart"
click node_home "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/home_screen.dart"
click node_player_setup "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/player_setup_screen.dart"
click node_mode_setup "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/game_mode_screen.dart"
click node_game_config "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/game_config_screen.dart"
click node_category_setup "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/category_selection_screen.dart"
click node_ready "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/ready_screen.dart"
click node_role_reveal "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/role_reveal_screen.dart"
click node_discussion "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/discussion_screen.dart"
click node_voting "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/voting_screen.dart"
click node_vote_results "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/vote_result_screen.dart"
click node_final_guess "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/final_guess_screen.dart"
click node_game_over "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/game_over_screen.dart"
click node_engine "https://github.com/mhdsahil1/who_knows/blob/main/lib/game/game_engine.dart"
click node_roles "https://github.com/mhdsahil1/who_knows/blob/main/lib/game/role_manager.dart"
click node_vote_rules "https://github.com/mhdsahil1/who_knows/blob/main/lib/game/vote_manager.dart"
click node_win_rules "https://github.com/mhdsahil1/who_knows/blob/main/lib/game/win_condition.dart"
click node_word_rules "https://github.com/mhdsahil1/who_knows/blob/main/lib/game/word_manager.dart"
click node_word_database "https://github.com/mhdsahil1/who_knows/blob/main/lib/data/word_database.dart"
click node_custom_words "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/my_words_screen.dart"
click node_custom_service "https://github.com/mhdsahil1/who_knows/blob/main/lib/services/my_words_service.dart"
click node_associated_words "https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/associated_words_screen.dart"
click node_associated_service "https://github.com/mhdsahil1/who_knows/blob/main/lib/services/associated_words_service.dart"
click node_storage "https://github.com/mhdsahil1/who_knows/blob/main/lib/services/storage_service.dart"

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_app,node_home,node_player_setup,node_mode_setup,node_game_config,node_ready,node_role_reveal,node_discussion,node_voting,node_vote_results,node_final_guess,node_game_over toneBlue
class node_engine,node_roles,node_vote_rules,node_win_rules toneAmber
class node_category_setup,node_word_rules,node_word_database,node_custom_words,node_associated_words,node_associated_service toneMint
class node_custom_service,node_storage toneRose
class node_players toneIndigo
```

## Components

### Game experience

- [App entry](https://github.com/mhdsahil1/who_knows/blob/main/lib/main.dart): `lib/main.dart`
- [App shell](https://github.com/mhdsahil1/who_knows/blob/main/lib/app.dart): `lib/app.dart`
- [Home](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/home_screen.dart): `lib/screens/home_screen.dart`
- [Player setup](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/player_setup_screen.dart): `lib/screens/player_setup_screen.dart`
- [Mode setup](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/game_mode_screen.dart): `lib/screens/game_mode_screen.dart`
- [Game configuration](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/game_config_screen.dart): `lib/screens/game_config_screen.dart`
- [Ready screen](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/ready_screen.dart): `lib/screens/ready_screen.dart`
- [Role reveal](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/role_reveal_screen.dart): `lib/screens/role_reveal_screen.dart`
- [Discussion](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/discussion_screen.dart): `lib/screens/discussion_screen.dart`
- [Voting](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/voting_screen.dart): `lib/screens/voting_screen.dart`
- [Vote results](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/vote_result_screen.dart): `lib/screens/vote_result_screen.dart`
- [Final guess](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/final_guess_screen.dart): `lib/screens/final_guess_screen.dart`
- [Game result](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/game_over_screen.dart): `lib/screens/game_over_screen.dart`

### Game rules

- [Game engine](https://github.com/mhdsahil1/who_knows/blob/main/lib/game/game_engine.dart): `lib/game/game_engine.dart`
- [Role assignment](https://github.com/mhdsahil1/who_knows/blob/main/lib/game/role_manager.dart): `lib/game/role_manager.dart`
- [Vote rules](https://github.com/mhdsahil1/who_knows/blob/main/lib/game/vote_manager.dart): `lib/game/vote_manager.dart`
- [Win conditions](https://github.com/mhdsahil1/who_knows/blob/main/lib/game/win_condition.dart): `lib/game/win_condition.dart`

### Word systems

- [Word selection](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/category_selection_screen.dart): `lib/screens/category_selection_screen.dart`
- [Word selection logic](https://github.com/mhdsahil1/who_knows/blob/main/lib/game/word_manager.dart): `lib/game/word_manager.dart`
- [Built-in words](https://github.com/mhdsahil1/who_knows/blob/main/lib/data/word_database.dart): `lib/data/word_database.dart`
- [Custom words](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/my_words_screen.dart): `lib/screens/my_words_screen.dart`
- [Associated Words](https://github.com/mhdsahil1/who_knows/blob/main/lib/screens/associated_words_screen.dart): `lib/screens/associated_words_screen.dart`
- [Association service](https://github.com/mhdsahil1/who_knows/blob/main/lib/services/associated_words_service.dart): `lib/services/associated_words_service.dart`

### Local data

- [Custom word service](https://github.com/mhdsahil1/who_knows/blob/main/lib/services/my_words_service.dart): `lib/services/my_words_service.dart`
- [Local storage](https://github.com/mhdsahil1/who_knows/blob/main/lib/services/storage_service.dart): `lib/services/storage_service.dart`

### Other components

- **Player group**

## Connections

- Player group → App entry: launches
- App entry → App shell: starts
- App shell → Home: opens
- Home → Player setup: starts game
- Player setup → Mode setup: continues setup
- Mode setup → Game configuration: selects mode
- Game configuration → Word selection: sets options
- Word selection → Ready screen: confirms words
- Ready screen → Role reveal: begins round
- Role reveal → Discussion: reveals roles
- Discussion → Voting: opens vote
- Voting → Vote results: submits vote
- Vote results → Win conditions: checks outcome
- Vote results → Final guess: caught Imposter
- Final guess → Win conditions: checks guess
- Win conditions → Game result: determines result
- Vote results → Ready screen: starts next round
- Role reveal → Role assignment: role assignment stage
- Voting → Vote rules: vote stage
- Word selection → Word selection logic: chooses words
- Word selection logic → Built-in words: reads categories
- Custom words → Custom word service: manages words
- Custom word service → Local storage: persists locally
- Associated Words → Association service: requests associations