# sidhant947/learnmath architecture

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

- Interactive diagram: https://gitdiagram.com/sidhant947/learnmath
- Repository: https://github.com/sidhant947/learnmath

## Overview

LearnMath is a Flutter mental-math training game, playable in a browser and distributed for Android. The intended user journey is to enter the app, choose a level or mode, solve math challenges, and review progress; the tree also shows settings, localized UI, and learning aids. Feature paths are taken from the tree, but their implementations were not excerpted, so internal control and data-flow links are dashed and unverified. The README establishes the product and platforms, but does not document the detailed gameplay flow.

Main entry points: [`lib/ui/features/game/math_game/math_game_screen.dart`](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/game/math_game/math_game_screen.dart) (Game screen), [`lib/data/repositories/progress_repository.dart`](https://github.com/sidhant947/learnmath/blob/main/lib/data/repositories/progress_repository.dart) (Progress repository), [`lib/ui/features/home/views/home_view.dart`](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/home/views/home_view.dart) (Home), [`lib/main.dart`](https://github.com/sidhant947/learnmath/blob/main/lib/main.dart) (App entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_app_entry["App entry<br/>[main.dart]"]
  node_home["Home<br/>[home_view.dart]"]
  node_home_vm["Home state"]
  node_level_select["Level selection"]
end

subgraph group_game["Math challenges"]
  node_game_screen["Game screen"]
  node_game_provider["Game state"]
  node_game_engine["Challenge engine"]
  node_math_problem["Math problem<br/>[math_problem.dart]"]
  node_duel["Duel mode<br/>[duel_screen.dart]"]
  node_survival["Survival mode"]
  node_target24["Target 24 mode"]
  node_time_attack["Time attack"]
end

subgraph group_learning["Learning aids"]
  node_step_explanation["Step explanations"]
  node_math_visualizer["Math visualizer"]
  node_scratchpad["Scratchpad"]
end

subgraph group_progress["Progress and settings"]
  node_stats["Statistics<br/>[stats_view.dart]"]
  node_progress_repo["Progress repository"]
  node_user_progress["User progress<br/>[user_progress.dart]"]
  node_badge["Badges<br/>[badge_item.dart]"]
  node_settings["Settings<br/>[settings_view.dart]"]
end

subgraph group_foundation["App foundation"]
  node_hive[("Local persistence<br/>[hive_service.dart]")]
  node_progress_adapter["Progress adapter"]
  node_localization["Localization"]
end

node_player(("Player"))

node_player -->|"opens"| node_app_entry
node_app_entry -.->|"starts"| node_home
node_home -.->|"uses state"| node_home_vm
node_home -.->|"offers levels"| node_level_select
node_level_select -.->|"starts challenge"| node_game_screen
node_home -.->|"starts play"| node_game_screen
node_game_screen -.->|"uses state"| node_game_provider
node_game_provider -.->|"delegates challenge"| node_game_engine
node_game_engine -.->|"creates problems"| node_math_problem
node_game_screen -.->|"offers mode"| node_duel
node_game_screen -.->|"offers mode"| node_survival
node_game_screen -.->|"offers mode"| node_target24
node_game_screen -.->|"offers mode"| node_time_attack
node_game_screen -.->|"shows steps"| node_step_explanation
node_step_explanation -.->|"visualizes math"| node_math_visualizer
node_game_screen -.->|"opens scratchpad"| node_scratchpad
node_game_screen -.->|"records results"| node_progress_repo
node_stats -.->|"reads progress"| node_progress_repo
node_progress_repo -.->|"maps progress"| node_user_progress
node_progress_repo -.->|"uses badges"| node_badge
node_progress_repo -.->|"persists data"| node_hive
node_progress_repo -.->|"adapts progress"| node_progress_adapter
node_settings -.->|"stores preferences"| node_hive
node_home -.->|"uses strings"| node_localization

click node_app_entry "https://github.com/sidhant947/learnmath/blob/main/lib/main.dart"
click node_home "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/home/views/home_view.dart"
click node_home_vm "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/home/view_models/home_view_model.dart"
click node_level_select "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/level_select/views/level_select_view.dart"
click node_game_screen "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/game/math_game/math_game_screen.dart"
click node_game_provider "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/game/math_game/math_game_provider.dart"
click node_game_engine "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/game/math_game/math_game_engine.dart"
click node_math_problem "https://github.com/sidhant947/learnmath/blob/main/lib/domain/models/math_problem.dart"
click node_duel "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/modes/duel/duel_screen.dart"
click node_survival "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/modes/survival/survival_screen.dart"
click node_target24 "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/modes/target24/target24_screen.dart"
click node_time_attack "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/modes/time_attack/time_attack_screen.dart"
click node_step_explanation "https://github.com/sidhant947/learnmath/blob/main/lib/ui/core/widgets/step_explanation_modal.dart"
click node_math_visualizer "https://github.com/sidhant947/learnmath/blob/main/lib/ui/core/widgets/rich_math_visualizer.dart"
click node_scratchpad "https://github.com/sidhant947/learnmath/blob/main/lib/ui/core/widgets/scratchpad_modal.dart"
click node_stats "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/stats/stats_view.dart"
click node_progress_repo "https://github.com/sidhant947/learnmath/blob/main/lib/data/repositories/progress_repository.dart"
click node_user_progress "https://github.com/sidhant947/learnmath/blob/main/lib/domain/models/user_progress.dart"
click node_badge "https://github.com/sidhant947/learnmath/blob/main/lib/domain/models/badge_item.dart"
click node_settings "https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/settings/views/settings_view.dart"
click node_hive "https://github.com/sidhant947/learnmath/blob/main/lib/data/services/hive_service.dart"
click node_progress_adapter "https://github.com/sidhant947/learnmath/blob/main/lib/data/services/user_progress_adapter.dart"
click node_localization "https://github.com/sidhant947/learnmath/blob/main/lib/l10n/app_localizations.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_app_entry,node_home,node_home_vm,node_level_select toneBlue
class node_game_screen,node_game_provider,node_game_engine,node_math_problem,node_duel,node_survival,node_target24,node_time_attack toneAmber
class node_step_explanation,node_math_visualizer,node_scratchpad toneMint
class node_stats,node_progress_repo,node_user_progress,node_badge,node_settings toneRose
class node_hive,node_progress_adapter,node_localization,node_player toneIndigo
```

## Components

### App experience

- [App entry](https://github.com/sidhant947/learnmath/blob/main/lib/main.dart): `lib/main.dart`
- [Home](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/home/views/home_view.dart): `lib/ui/features/home/views/home_view.dart`
- [Home state](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/home/view_models/home_view_model.dart): `lib/ui/features/home/view_models/home_view_model.dart`
- [Level selection](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/level_select/views/level_select_view.dart): `lib/ui/features/level_select/views/level_select_view.dart`

### Math challenges

- [Game screen](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/game/math_game/math_game_screen.dart): `lib/ui/features/game/math_game/math_game_screen.dart`
- [Game state](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/game/math_game/math_game_provider.dart): `lib/ui/features/game/math_game/math_game_provider.dart`
- [Challenge engine](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/game/math_game/math_game_engine.dart): `lib/ui/features/game/math_game/math_game_engine.dart`
- [Math problem](https://github.com/sidhant947/learnmath/blob/main/lib/domain/models/math_problem.dart): `lib/domain/models/math_problem.dart`
- [Duel mode](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/modes/duel/duel_screen.dart): `lib/ui/features/modes/duel/duel_screen.dart`
- [Survival mode](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/modes/survival/survival_screen.dart): `lib/ui/features/modes/survival/survival_screen.dart`
- [Target 24 mode](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/modes/target24/target24_screen.dart): `lib/ui/features/modes/target24/target24_screen.dart`
- [Time attack](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/modes/time_attack/time_attack_screen.dart): `lib/ui/features/modes/time_attack/time_attack_screen.dart`

### Learning aids

- [Step explanations](https://github.com/sidhant947/learnmath/blob/main/lib/ui/core/widgets/step_explanation_modal.dart): `lib/ui/core/widgets/step_explanation_modal.dart`
- [Math visualizer](https://github.com/sidhant947/learnmath/blob/main/lib/ui/core/widgets/rich_math_visualizer.dart): `lib/ui/core/widgets/rich_math_visualizer.dart`
- [Scratchpad](https://github.com/sidhant947/learnmath/blob/main/lib/ui/core/widgets/scratchpad_modal.dart): `lib/ui/core/widgets/scratchpad_modal.dart`

### Progress and settings

- [Statistics](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/stats/stats_view.dart): `lib/ui/features/stats/stats_view.dart`
- [Progress repository](https://github.com/sidhant947/learnmath/blob/main/lib/data/repositories/progress_repository.dart): `lib/data/repositories/progress_repository.dart`
- [User progress](https://github.com/sidhant947/learnmath/blob/main/lib/domain/models/user_progress.dart): `lib/domain/models/user_progress.dart`
- [Badges](https://github.com/sidhant947/learnmath/blob/main/lib/domain/models/badge_item.dart): `lib/domain/models/badge_item.dart`
- [Settings](https://github.com/sidhant947/learnmath/blob/main/lib/ui/features/settings/views/settings_view.dart): `lib/ui/features/settings/views/settings_view.dart`

### App foundation

- [Local persistence](https://github.com/sidhant947/learnmath/blob/main/lib/data/services/hive_service.dart): `lib/data/services/hive_service.dart`
- [Progress adapter](https://github.com/sidhant947/learnmath/blob/main/lib/data/services/user_progress_adapter.dart): `lib/data/services/user_progress_adapter.dart`
- [Localization](https://github.com/sidhant947/learnmath/blob/main/lib/l10n/app_localizations.dart): `lib/l10n/app_localizations.dart`

### Other components

- **Player**

## Connections

- Player → App entry: opens (evidence: `README.md`)
- App entry → Home: starts
- Home → Home state: uses state
- Home → Level selection: offers levels
- Level selection → Game screen: starts challenge
- Home → Game screen: starts play
- Game screen → Game state: uses state
- Game state → Challenge engine: delegates challenge
- Challenge engine → Math problem: creates problems
- Game screen → Duel mode: offers mode
- Game screen → Survival mode: offers mode
- Game screen → Target 24 mode: offers mode
- Game screen → Time attack: offers mode
- Game screen → Step explanations: shows steps
- Step explanations → Math visualizer: visualizes math
- Game screen → Scratchpad: opens scratchpad
- Game screen → Progress repository: records results
- Statistics → Progress repository: reads progress
- Progress repository → User progress: maps progress
- Progress repository → Badges: uses badges
- Progress repository → Local persistence: persists data
- Progress repository → Progress adapter: adapts progress
- Settings → Local persistence: stores preferences
- Home → Localization: uses strings