# agtrlabs/sozzle architecture

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

- Interactive diagram: https://gitdiagram.com/agtrlabs/sozzle
- Repository: https://github.com/agtrlabs/sozzle

## Overview

Sozzle is a Flutter word-puzzle game. The main user journey is entering from the home screen, playing a level, and reaching its completion/reward screen; level and progress repositories support game state. The tree also identifies settings, audio, localization, and a reusable crossword-level generator. Source excerpts mainly cover native launchers, so the Dart relationships below reflect the module structure and product flow rather than verified call sites.

Main entry points: [`lib/src/game_play/view/game_play_page.dart`](https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_play/view/game_play_page.dart) (Puzzle screen), [`lib/src/game_core/coordinator/game_core_coordinator.dart`](https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_core/coordinator/game_core_coordinator.dart) (Game coordinator), [`lib/src/home/view/home_page.dart`](https://github.com/agtrlabs/sozzle/blob/main/lib/src/home/view/home_page.dart) (Home screen), [`lib/bootstrap.dart`](https://github.com/agtrlabs/sozzle/blob/main/lib/bootstrap.dart) (App bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_bootstrap["App bootstrap<br/>[bootstrap.dart]"]
  node_routes["Navigation routes<br/>[routes.dart]"]
  node_home["Home screen<br/>[home_page.dart]"]
end

subgraph group_play["Puzzle play"]
  node_game_view["Puzzle screen"]
  node_play_bloc["Play controller"]
  node_completion["Level completion"]
end

subgraph group_state["Game state"]
  node_game_core["Game coordinator"]
  node_core_bloc["Core game state"]
  node_level_adapter["Level adapter"]
  node_level_repo["Level repository"]
  node_level_data["Level definitions"]
  node_progress_adapter["Progress adapter"]
  node_progress_repo["Progress repository"]
end

subgraph group_support["Player support"]
  node_settings["Settings<br/>[settings_page.dart]"]
  node_audio["Audio controller"]
  node_assets["Game assets"]
  node_generator["Crossword generator"]
  node_word_list["Word lists<br/>[wordlist.txt]"]
  node_localization["Translations"]
end

node_player(("Player"))

node_player -->|"launches"| node_bootstrap
node_bootstrap -->|"starts navigation"| node_routes
node_routes -->|"opens"| node_home
node_player -->|"chooses play"| node_home
node_home -->|"starts level"| node_game_view
node_game_view -->|"sends guesses"| node_play_bloc
node_play_bloc -->|"coordinates game"| node_game_core
node_game_core -->|"updates state"| node_core_bloc
node_game_core -->|"requests levels"| node_level_adapter
node_level_adapter -->|"loads level"| node_level_repo
node_level_repo -->|"reads definitions"| node_level_data
node_game_core -->|"updates progress"| node_progress_adapter
node_progress_adapter -->|"stores progress"| node_progress_repo
node_game_view -->|"shows completion"| node_completion
node_completion -->|"advances level"| node_game_view
node_player -->|"adjusts settings"| node_settings
node_game_view -.->|"plays effects"| node_audio
node_game_view -->|"renders with"| node_assets
node_generator -->|"uses words"| node_word_list
node_home -->|"displays strings"| node_localization

click node_bootstrap "https://github.com/agtrlabs/sozzle/blob/main/lib/bootstrap.dart"
click node_routes "https://github.com/agtrlabs/sozzle/blob/main/lib/core/routes/routes.dart"
click node_home "https://github.com/agtrlabs/sozzle/blob/main/lib/src/home/view/home_page.dart"
click node_game_view "https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_play/view/game_play_page.dart"
click node_play_bloc "https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_play/bloc/game_play_bloc.dart"
click node_game_core "https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_core/coordinator/game_core_coordinator.dart"
click node_core_bloc "https://github.com/agtrlabs/sozzle/blob/main/packages/game_core/lib/src/bloc/game_core_bloc.dart"
click node_level_adapter "https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_core/adapters/level_repository_adapter.dart"
click node_level_repo "https://github.com/agtrlabs/sozzle/blob/main/lib/src/level/application/level_repository.dart"
click node_level_data "https://github.com/agtrlabs/sozzle/blob/main/packages/level_data/lib/src/level_data_base.dart"
click node_progress_adapter "https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_core/adapters/user_progress_repository_adapter.dart"
click node_progress_repo "https://github.com/agtrlabs/sozzle/blob/main/lib/src/user_stats/application/user_stats_repository.dart"
click node_completion "https://github.com/agtrlabs/sozzle/blob/main/lib/src/level_won/view/level_complete_page.dart"
click node_settings "https://github.com/agtrlabs/sozzle/blob/main/lib/src/settings/view/settings_page.dart"
click node_audio "https://github.com/agtrlabs/sozzle/blob/main/lib/src/audio/audio_controller.dart"
click node_assets "https://github.com/agtrlabs/sozzle/tree/main/assets"
click node_generator "https://github.com/agtrlabs/sozzle/blob/main/packages/level_generator/lib/src/app/crossword_generator.dart"
click node_word_list "https://github.com/agtrlabs/sozzle/blob/main/assets/words/wordlist.txt"
click node_localization "https://github.com/agtrlabs/sozzle/tree/main/lib/l10n/arb"

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_bootstrap,node_routes,node_home toneBlue
class node_game_view,node_play_bloc,node_completion toneAmber
class node_game_core,node_core_bloc,node_level_adapter,node_level_repo,node_level_data,node_progress_adapter,node_progress_repo toneMint
class node_settings,node_audio,node_assets,node_generator,node_word_list,node_localization toneRose
class node_player toneIndigo
```

## Components

### App shell

- [App bootstrap](https://github.com/agtrlabs/sozzle/blob/main/lib/bootstrap.dart): `lib/bootstrap.dart`
- [Navigation routes](https://github.com/agtrlabs/sozzle/blob/main/lib/core/routes/routes.dart): `lib/core/routes/routes.dart`
- [Home screen](https://github.com/agtrlabs/sozzle/blob/main/lib/src/home/view/home_page.dart): `lib/src/home/view/home_page.dart`

### Puzzle play

- [Puzzle screen](https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_play/view/game_play_page.dart): `lib/src/game_play/view/game_play_page.dart`
- [Play controller](https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_play/bloc/game_play_bloc.dart): `lib/src/game_play/bloc/game_play_bloc.dart`
- [Level completion](https://github.com/agtrlabs/sozzle/blob/main/lib/src/level_won/view/level_complete_page.dart): `lib/src/level_won/view/level_complete_page.dart`

### Game state

- [Game coordinator](https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_core/coordinator/game_core_coordinator.dart): `lib/src/game_core/coordinator/game_core_coordinator.dart`
- [Core game state](https://github.com/agtrlabs/sozzle/blob/main/packages/game_core/lib/src/bloc/game_core_bloc.dart): `packages/game_core/lib/src/bloc/game_core_bloc.dart`
- [Level adapter](https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_core/adapters/level_repository_adapter.dart): `lib/src/game_core/adapters/level_repository_adapter.dart`
- [Level repository](https://github.com/agtrlabs/sozzle/blob/main/lib/src/level/application/level_repository.dart): `lib/src/level/application/level_repository.dart`
- [Level definitions](https://github.com/agtrlabs/sozzle/blob/main/packages/level_data/lib/src/level_data_base.dart): `packages/level_data/lib/src/level_data_base.dart`
- [Progress adapter](https://github.com/agtrlabs/sozzle/blob/main/lib/src/game_core/adapters/user_progress_repository_adapter.dart): `lib/src/game_core/adapters/user_progress_repository_adapter.dart`
- [Progress repository](https://github.com/agtrlabs/sozzle/blob/main/lib/src/user_stats/application/user_stats_repository.dart): `lib/src/user_stats/application/user_stats_repository.dart`

### Player support

- [Settings](https://github.com/agtrlabs/sozzle/blob/main/lib/src/settings/view/settings_page.dart): `lib/src/settings/view/settings_page.dart`
- [Audio controller](https://github.com/agtrlabs/sozzle/blob/main/lib/src/audio/audio_controller.dart): `lib/src/audio/audio_controller.dart`
- [Game assets](https://github.com/agtrlabs/sozzle/tree/main/assets): `assets`
- [Crossword generator](https://github.com/agtrlabs/sozzle/blob/main/packages/level_generator/lib/src/app/crossword_generator.dart): `packages/level_generator/lib/src/app/crossword_generator.dart`
- [Word lists](https://github.com/agtrlabs/sozzle/blob/main/assets/words/wordlist.txt): `assets/words/wordlist.txt`
- [Translations](https://github.com/agtrlabs/sozzle/tree/main/lib/l10n/arb): `lib/l10n/arb`

### Other components

- **Player**

## Connections

- Player → App bootstrap: launches
- App bootstrap → Navigation routes: starts navigation
- Navigation routes → Home screen: opens
- Player → Home screen: chooses play
- Home screen → Puzzle screen: starts level
- Puzzle screen → Play controller: sends guesses
- Play controller → Game coordinator: coordinates game
- Game coordinator → Core game state: updates state
- Game coordinator → Level adapter: requests levels
- Level adapter → Level repository: loads level
- Level repository → Level definitions: reads definitions
- Game coordinator → Progress adapter: updates progress
- Progress adapter → Progress repository: stores progress
- Puzzle screen → Level completion: shows completion
- Level completion → Puzzle screen: advances level
- Player → Settings: adjusts settings
- Puzzle screen → Audio controller: plays effects
- Puzzle screen → Game assets: renders with
- Crossword generator → Word lists: uses words
- Home screen → Translations: displays strings