# pharshilladila/typing-speed-master architecture

> Architecture diagram of the GitHub repository pharshilladila/typing-speed-master, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pharshilladila/typing-speed-master
- Repository: https://github.com/pharshilladila/typing-speed-master

## Overview

1. This is a Flutter cross-platform app, but the primary product is a web typing trainer/analytics app. The repo also contains Android scaffolding, so the same codebase can be packaged for mobile, though the architecture is centered on Flutter web deployment.

2. The app is organized around a feature-first layout under `lib/features`, with shared UI and utilities in `lib/widgets`, `lib/helper`, `lib/utils`, and `lib/models`. Each major screen owns its own model/provider/widget subfolders, which makes the architecture mostly modular by feature rather than by technical layer.

3. The root entry point is `lib/main.dart`, which likely wires together global services, providers, theming, and routing before handing off to `app_entry_point.dart`. The app-wide composition is managed through `lib/providers/app_providers.dart`, `auth_provider.dart`, `router_provider.dart`, `test_goal_provider.dart`, and `theme/provider/theme_provider.dart`.

4. Navigation is centralized in `lib/routes/app_router.dart`. The named screens in the tree suggest a route map that spans the typing test flow, results flow, dashboard, history, profile/settings, certificates, and game modes.

5. The core product flow is the typing test pipeline: `typing_test_screen.dart` collects keystrokes and timing, `typing_test_provider.dart` computes live metrics, and `results_screen.dart` presents the completed session. Supporting widgets like `text_display_widget.dart` and `character_analysis_widget.dart` indicate character-level feedback and real-time correctness tracking.

6. Persistent analytics are modeled separately from the live test UI. Shared domain objects such as `typing_test_result_model.dart`, `typing_stat_data.dart`, `user_model.dart`, and `test_goal_model.dart` feed the dashboard, history, and profile statistics views. The dashboard screens use chart widgets to visualize trend data rather than recomputing metrics in the UI.

7. The app has a distinct analytics/dashboard subsystem under `lib/features/dashboard` and `lib/features/history`. These screens consume aggregated result data to show WPM, accuracy, performance by difficulty, radar-style summaries, and historical lists, with reusable cards/shimmer/loading states in shared widgets.

8. Authentication and user state are a separate concern from the typing engine. The README and `auth_provider.dart` indicate Google sign-in and guest usage, with Supabase as the persistence backend for saved results and user data. Profile screens and providers build on that authenticated user context to show stats, preferences, and account management.

9. There is a game subsystem under `lib/features/games` that extends the typing experience into alternative mini-games: character rush, word master, and word reflex. A `game_dashboard_provider.dart` and common game widgets suggest these are coordinated under a shared game dashboard but remain isolated from the main test flow.

10. Certificates are treated as a specialized output path rather than a core test flow. The certificate feature has its own model, provider, and custom painter, which implies it generates shareable or printable certificates from achieved test results.

11. The profile area bundles non-core but user-facing configuration and legal content: login/register states, theme and notification preferences, activity summaries, update/details widgets, and privacy/terms pages. This area acts as the account/settings boundary for personalization and compliance.

12. Shared UI primitives are heavily reused across features: custom app bars, drawers, dropdowns, dialogs, toast messages, result cards, responsive layout helpers, and background decorations. This indicates the app’s visual consistency is enforced through a component library in `lib/widgets`, not duplicated inside screens.

13. The repository also includes deployment/runtime artifacts that matter architecturally: `web/manifest.json`, `web/firebase-messaging-sw.js`, and `web/ads.txt` for web delivery, plus `android/app/google-services.json` for Android-side Firebase configuration. `vercel.json`, `railway.json`, and `nixpacks.toml` show the app is prepared for multiple hosting/build targets, with the web build likely deployed externally.

14. In summary, the main architecture is: Flutter UI at the top, feature modules in the middle, shared providers/models beneath, and external services at the edge for auth, persistence, and deployment. The important boundaries to diagram are the typing-test runtime, analytics/history read models, account/profile state, game extensions, and the reusable app shell that ties them together.

Main entry points: [`lib/routes/app_router.dart`](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/routes/app_router.dart) (router), [`lib/providers/app_providers.dart`](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/providers/app_providers.dart) (providers), [`lib/main.dart`](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/main.dart) (main.dart), [`lib/features/typing_test/provider/typing_test_provider.dart`](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/provider/typing_test_provider.dart) (typing engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App Shell"]
  node_main["main.dart<br/>entrypoint<br/>[main.dart]"]
  node_entry_point["app entry<br/>bootstrap"]
  node_app_router["router<br/>navigation<br/>[app_router.dart]"]
end

subgraph group_core_state["Core State"]
  node_app_providers["providers<br/>composition<br/>[app_providers.dart]"]
  node_auth_provider["auth<br/>session state<br/>[auth_provider.dart]"]
  node_theme_provider["theme<br/>ui state"]
  node_test_goal_provider["test goal<br/>goal state"]
  node_shared_models["domain models<br/>data models"]
end

subgraph group_typing["Typing Flow"]
  node_typing_provider["typing engine<br/>live metrics"]
  node_typing_screen["typing test<br/>screen"]
  node_typing_widgets["text feedback<br/>ui widgets"]
  node_results_screen["results<br/>screen"]
end

subgraph group_analytics["Analytics"]
  node_dashboard_screen["dashboard<br/>analytics screen"]
  node_history_screen["history<br/>analytics screen"]
  node_analytics_widgets["charts<br/>visualization widgets"]
  node_certificate["certificate<br/>output flow"]
end

subgraph group_account["Account"]
  node_profile_screen["profile<br/>account screen"]
  node_profile_widgets["profile widgets<br/>account ui"]
end

subgraph group_games["Games"]
  node_game_dashboard["games hub<br/>game launcher"]
  node_game_modes["game modes<br/>mini-games"]
end

subgraph group_shared_ui["Shared UI"]
  node_shared_widgets["shared widgets<br/>ui kit<br/>[custom_appbar.dart]"]
end

subgraph group_deployment["Deployment"]
  node_web_config["web config<br/>web delivery<br/>[manifest.json]"]
  node_android_config["android config<br/>mobile delivery"]
end

node_main -->|"boots"| node_entry_point
node_main -->|"wraps"| node_app_providers
node_main -->|"starts navigation"| node_app_router
node_app_providers -->|"includes"| node_auth_provider
node_app_providers -->|"includes"| node_theme_provider
node_app_providers -->|"includes"| node_test_goal_provider
node_app_providers -->|"includes"| node_typing_provider
node_app_router -->|"routes to"| node_typing_screen
node_app_router -->|"routes to"| node_results_screen
node_app_router -->|"routes to"| node_dashboard_screen
node_app_router -->|"routes to"| node_history_screen
node_app_router -->|"routes to"| node_profile_screen
node_app_router -->|"routes to"| node_game_dashboard
node_app_router -->|"routes to"| node_certificate
node_typing_screen -->|"drives"| node_typing_provider
node_typing_screen -->|"renders"| node_typing_widgets
node_typing_provider -->|"produces"| node_shared_models
node_typing_provider -->|"feeds"| node_results_screen
node_results_screen -->|"exports"| node_certificate
node_dashboard_screen -->|"visualizes"| node_analytics_widgets
node_history_screen -->|"reads"| node_shared_models
node_profile_screen -->|"uses"| node_auth_provider
node_profile_screen -->|"composes"| node_profile_widgets
node_game_dashboard -->|"launches"| node_game_modes
node_game_modes -->|"reuses"| node_shared_widgets
node_certificate -->|"consumes"| node_shared_models
node_shared_widgets -->|"binds"| node_shared_models
node_web_config -->|"deploys"| node_main
node_android_config -->|"packages"| node_main

click node_main "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/main.dart"
click node_entry_point "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/app_entry_point.dart"
click node_app_router "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/routes/app_router.dart"
click node_app_providers "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/providers/app_providers.dart"
click node_auth_provider "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/providers/auth_provider.dart"
click node_theme_provider "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/theme/provider/theme_provider.dart"
click node_test_goal_provider "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/providers/test_goal_provider.dart"
click node_typing_provider "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/provider/typing_test_provider.dart"
click node_typing_screen "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/typing_test_screen.dart"
click node_typing_widgets "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/widget/text_display_widget.dart"
click node_results_screen "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/results_screen.dart"
click node_dashboard_screen "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/dashboard/dashboard_screen.dart"
click node_history_screen "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/history/history_screen.dart"
click node_analytics_widgets "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/dashboard/widget/accuracy_chart.dart"
click node_profile_screen "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/profile/profile_screen.dart"
click node_profile_widgets "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/profile/widget/profile_auth_tabs_and_section.dart"
click node_game_dashboard "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/games/game_dashboard_screen.dart"
click node_game_modes "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/games/game_character_rush/game_character_rush_screen.dart"
click node_certificate "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/certificate/test_certificate.dart"
click node_shared_widgets "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/widgets/custom_appbar.dart"
click node_shared_models "https://github.com/pharshilladila/typing-speed-master/blob/main/lib/models/typing_test_result_model.dart"
click node_web_config "https://github.com/pharshilladila/typing-speed-master/blob/main/web/manifest.json"
click node_android_config "https://github.com/pharshilladila/typing-speed-master/blob/main/android/app/google-services.json"

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_main,node_entry_point,node_app_router,node_shared_widgets toneBlue
class node_app_providers,node_auth_provider,node_theme_provider,node_test_goal_provider,node_shared_models,node_web_config,node_android_config toneAmber
class node_typing_provider,node_typing_screen,node_typing_widgets,node_results_screen toneMint
class node_dashboard_screen,node_history_screen,node_analytics_widgets,node_certificate toneRose
class node_profile_screen,node_profile_widgets toneIndigo
class node_game_dashboard,node_game_modes toneTeal
```

## Components

### App Shell

- [main.dart](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/main.dart): entrypoint · App bootstrap and global wiring. · `lib/main.dart`
- [app entry](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/app_entry_point.dart): bootstrap · Secondary app composition entry. · `lib/features/app_entry_point.dart`
- [router](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/routes/app_router.dart): navigation · Central route map for the app. · `lib/routes/app_router.dart`

### Core State

- [providers](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/providers/app_providers.dart): composition · Global provider assembly. · `lib/providers/app_providers.dart`
- [auth](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/providers/auth_provider.dart): session state · Authenticated and guest user state. · `lib/providers/auth_provider.dart`
- [theme](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/theme/provider/theme_provider.dart): ui state · App theme selection and persistence. · `lib/theme/provider/theme_provider.dart`
- [test goal](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/providers/test_goal_provider.dart): goal state · Typing goal setup and progress. · `lib/providers/test_goal_provider.dart`
- [domain models](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/models/typing_test_result_model.dart): data models · Shared result, user, and goal models. · `lib/models/typing_test_result_model.dart`

### Typing Flow

- [typing engine](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/provider/typing_test_provider.dart): live metrics · Tracks keystrokes, timing, and session metrics. · `lib/features/typing_test/provider/typing_test_provider.dart`
- [typing test](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/typing_test_screen.dart): screen · Main typing interaction surface. · `lib/features/typing_test/typing_test_screen.dart`
- [text feedback](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/widget/text_display_widget.dart): ui widgets · Character-level display and analysis widgets. · `lib/features/typing_test/widget/text_display_widget.dart`
- [results](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/typing_test/results_screen.dart): screen · Completed typing session summary. · `lib/features/typing_test/results_screen.dart`

### Analytics

- [dashboard](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/dashboard/dashboard_screen.dart): analytics screen · Aggregated performance overview. · `lib/features/dashboard/dashboard_screen.dart`
- [history](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/history/history_screen.dart): analytics screen · Saved result timeline and list view. · `lib/features/history/history_screen.dart`
- [charts](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/dashboard/widget/accuracy_chart.dart): visualization widgets · Charts and summary visuals for stats. · `lib/features/dashboard/widget/accuracy_chart.dart`
- [certificate](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/certificate/test_certificate.dart): output flow · Generates shareable typing certificates. · `lib/features/certificate/test_certificate.dart`

### Account

- [profile](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/profile/profile_screen.dart): account screen · Account, preferences, and activity hub. · `lib/features/profile/profile_screen.dart`
- [profile widgets](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/profile/widget/profile_auth_tabs_and_section.dart): account ui · Login, register, stats, and preference panels. · `lib/features/profile/widget/profile_auth_tabs_and_section.dart`

### Games

- [games hub](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/games/game_dashboard_screen.dart): game launcher · Entry point for mini-games. · `lib/features/games/game_dashboard_screen.dart`
- [game modes](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/features/games/game_character_rush/game_character_rush_screen.dart): mini-games · Character rush, word master, and word reflex. · `lib/features/games/game_character_rush/game_character_rush_screen.dart`

### Shared UI

- [shared widgets](https://github.com/pharshilladila/typing-speed-master/blob/main/lib/widgets/custom_appbar.dart): ui kit · Reusable app chrome, cards, dialogs, and layout helpers. · `lib/widgets/custom_appbar.dart`

### Deployment

- [web config](https://github.com/pharshilladila/typing-speed-master/blob/main/web/manifest.json): web delivery · Browser delivery assets and messaging setup. · `web/manifest.json`
- [android config](https://github.com/pharshilladila/typing-speed-master/blob/main/android/app/google-services.json): mobile delivery · Android Firebase and app scaffolding. · `android/app/google-services.json`

## Connections

- main.dart → app entry: boots
- main.dart → providers: wraps
- main.dart → router: starts navigation
- providers → auth: includes
- providers → theme: includes
- providers → test goal: includes
- providers → typing engine: includes
- router → typing test: routes to
- router → results: routes to
- router → dashboard: routes to
- router → history: routes to
- router → profile: routes to
- router → games hub: routes to
- router → certificate: routes to
- typing test → typing engine: drives
- typing test → text feedback: renders
- typing engine → domain models: produces
- typing engine → results: feeds
- results → certificate: exports
- dashboard → charts: visualizes
- history → domain models: reads
- profile → auth: uses
- profile → profile widgets: composes
- games hub → game modes: launches
- game modes → shared widgets: reuses
- certificate → domain models: consumes
- shared widgets → domain models: binds
- web config → main.dart: deploys
- android config → main.dart: packages