# yussefz99/qalam architecture

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

- Interactive diagram: https://gitdiagram.com/yussefz99/qalam
- Repository: https://github.com/yussefz99/qalam

## Overview

1. This repository is a Flutter mobile app called “qalam,” focused on Arabic handwriting practice and early literacy. There is no obvious server-side component; the app appears to run fully on-device, with local persistence, asset-based curriculum, and optional ML-based recognition.

2. The runtime boundary starts at `lib/main.dart`, which boots the Flutter app, applies theming, and hands off to the router. The Android folder is just the platform shell for Flutter, with the standard `MainActivity.kt` and Android manifests.

3. Navigation is centralized in `lib/router/app_router.dart` and related route definitions. The route layer likely separates onboarding, home, practice, journey, demo, and settings flows, and tests indicate there is an onboarding gate and demo route handling.

4. The main product surfaces are split into feature modules:
   - `lib/features/onboarding` for initial user setup
   - `lib/screens/home_screen.dart`, `practice_screen.dart`, and `settings_screen.dart` for primary app entry points
   - `lib/features/journey` for progression visualization
   - `lib/features/practice` for the handwriting session experience

5. The handwriting practice flow is the core functional subsystem. It is composed of a canvas for stroke capture, visual guidance, ghost comparison, tutor/praise/feedback panels, stroke-order animation, and mastery celebration. This suggests an interaction loop of “show target -> capture ink -> evaluate -> give feedback -> progress state.”

6. Scoring and recognition are isolated in `lib/core`. The scoring pipeline includes stroke normalization, resampling, tolerance rules, geometric stroke scoring, and letter-level scoring. Recognition is separated into a recognizer abstraction plus an ML Kit-backed implementation, which implies the app can compare user input against reference paths and potentially use device ML for input interpretation.

7. Curriculum and learning content are asset-driven. `assets/curriculum/letters.json` and `lessons.json` are the source of lesson and letter definitions, while `lib/data/curriculum_repository.dart` and the `models/lesson.dart`, `letter.dart`, and `lesson_progression.dart` files turn that content into app-ready domain objects.

8. User and progress state are persisted locally. `lib/data/app_database.dart` plus Drift-generated files, along with repositories for child profiles and progress, indicate an offline-first local database layer. The repositories are the boundary between UI/state management and storage.

9. State management is provider-based. The `lib/providers` package contains providers for audio, journey, practice, profile, and progression, with generated Riverpod code. This layer mediates between UI screens and repositories/services, and likely coordinates session state, selected lesson/letter, and progression updates.

10. There is a service boundary for model downloads. `lib/services/model_download_service.dart` suggests the app can fetch or manage recognition models on-device, which is the main place where external network or device-managed model infrastructure could appear.

11. The app has a strong demo and presentation subsystem under `lib/demo` and `docs/presentation`. Demo screens like watch, trace, feedback, home, and celebration indicate a scripted user journey used for showcasing or stakeholder review, separate from the production learning flow.

12. `lib/dev` contains authoring and audit tools embedded in the app itself, such as glyph audit and authoring screens. This implies an internal content-validation workflow alongside the learner-facing app, probably used to inspect reference paths, glyph correctness, or curriculum content.

13. The UI is heavily themed and branded. `lib/theme`, `lib/widgets/arabic_text.dart`, and `lib/widgets/qalam_mascot.dart` form the shared presentation layer, while the `docs/design` tree contains the design system, previews, and UI kits that informed the app’s visual language.

14. The test suite mirrors the architecture closely: core scoring, curriculum validation, repositories, routing, onboarding, journey, practice, demo screens, themes, widgets, and golden tests. That layout is a good guide for diagramming boundaries, because it reflects the app’s actual subsystem decomposition.

15. The `.claude` and `.planning` directories are not runtime architecture; they are workflow, planning, and agent-instruction infrastructure for building and maintaining the app. They matter for development process, but not for the deployed product diagram.

Main entry points: [`lib/router/app_router.dart`](https://github.com/yussefz99/qalam/blob/main/lib/router/app_router.dart) (App router), [`lib/features/practice/practice_screen.dart`](https://github.com/yussefz99/qalam/blob/main/lib/features/practice/practice_screen.dart) (Practice loop), [`lib/providers/practice_providers.dart`](https://github.com/yussefz99/qalam/blob/main/lib/providers/practice_providers.dart) (Providers), [`lib/data/curriculum_repository.dart`](https://github.com/yussefz99/qalam/blob/main/lib/data/curriculum_repository.dart) (Curriculum repo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_main(("main.dart<br/>Flutter entry<br/>[main.dart]"))
  node_router["App router<br/>Navigation<br/>[app_router.dart]"]
  node_home["Home<br/>Screen<br/>[home_screen.dart]"]
  node_practice_screen["Practice screen"]
  node_settings["Settings<br/>Screen"]
  node_onboarding["Onboarding<br/>Feature flow"]
  node_journey["Journey<br/>Feature flow"]
  node_theme["Theme<br/>Design system<br/>[app_theme.dart]"]
  node_widgets["Shared widgets<br/>UI primitives<br/>[arabic_text.dart]"]
end

subgraph group_domain["Learning domain"]
  node_practice["Practice loop<br/>Feature subsystem"]
  node_canvas["Stroke canvas<br/>Input surface<br/>[stroke_canvas.dart]"]
  node_feedback["Feedback panels<br/>Guidance UI"]
  node_scoring["Scoring core<br/>Evaluation engine<br/>[letter_scorer.dart]"]
  node_recognition["Recognizer<br/>ML abstraction"]
  node_curriculum[("Curriculum repo<br/>Content source")]
  node_assets["Curriculum assets<br/>Static content<br/>[letters.json]"]
  node_models["Domain models<br/>Learning model<br/>[lesson.dart]"]
  node_database[("Local database<br/>Offline storage<br/>[app_database.dart]")]
  node_repos["Data repos<br/>Persistence boundary"]
  node_providers["Providers<br/>State layer"]
  node_model_dl["Model download"]
end

subgraph group_tooling["Demo and tools"]
  node_demo["Demo suite<br/>Presentation flow"]
  node_dev["Dev tools<br/>Authoring tools"]
  node_docs["Design docs<br/>External design assets<br/>[README.md]"]
end

node_main -->|"boots"| node_router
node_main -->|"applies"| node_theme
node_router -->|"routes to"| node_home
node_router -->|"gates"| node_onboarding
node_router -->|"routes to"| node_practice_screen
node_router -->|"routes to"| node_journey
node_router -->|"routes to"| node_settings
node_router -->|"routes to"| node_demo
node_home -->|"reads state"| node_providers
node_practice_screen -->|"hosts"| node_practice
node_practice -->|"captures"| node_canvas
node_practice -->|"shows"| node_feedback
node_practice -->|"evaluates"| node_scoring
node_practice -->|"interprets"| node_recognition
node_practice -->|"updates"| node_providers
node_providers -->|"loads/saves"| node_repos
node_repos -->|"persists"| node_database
node_curriculum -->|"reads"| node_assets
node_curriculum -->|"builds"| node_models
node_journey -->|"reads state"| node_providers
node_providers -->|"uses"| node_curriculum
node_model_dl -->|"supplies models"| node_recognition
node_dev -->|"audits"| node_curriculum
node_demo -->|"reuses"| node_widgets
node_theme -->|"styles"| node_widgets
node_docs -.->|"informs"| node_theme

click node_main "https://github.com/yussefz99/qalam/blob/main/lib/main.dart"
click node_router "https://github.com/yussefz99/qalam/blob/main/lib/router/app_router.dart"
click node_home "https://github.com/yussefz99/qalam/blob/main/lib/screens/home_screen.dart"
click node_practice_screen "https://github.com/yussefz99/qalam/blob/main/lib/screens/practice_screen.dart"
click node_settings "https://github.com/yussefz99/qalam/blob/main/lib/screens/settings_screen.dart"
click node_onboarding "https://github.com/yussefz99/qalam/blob/main/lib/features/onboarding/onboarding_screen.dart"
click node_journey "https://github.com/yussefz99/qalam/blob/main/lib/features/journey/journey_screen.dart"
click node_theme "https://github.com/yussefz99/qalam/blob/main/lib/theme/app_theme.dart"
click node_widgets "https://github.com/yussefz99/qalam/blob/main/lib/widgets/arabic_text.dart"
click node_practice "https://github.com/yussefz99/qalam/blob/main/lib/features/practice/practice_screen.dart"
click node_canvas "https://github.com/yussefz99/qalam/blob/main/lib/features/practice/widgets/stroke_canvas.dart"
click node_feedback "https://github.com/yussefz99/qalam/blob/main/lib/features/practice/widgets/feedback_panel.dart"
click node_scoring "https://github.com/yussefz99/qalam/blob/main/lib/core/scoring/letter_scorer.dart"
click node_recognition "https://github.com/yussefz99/qalam/blob/main/lib/core/recognition/handwriting_recognizer.dart"
click node_curriculum "https://github.com/yussefz99/qalam/blob/main/lib/data/curriculum_repository.dart"
click node_assets "https://github.com/yussefz99/qalam/blob/main/assets/curriculum/letters.json"
click node_models "https://github.com/yussefz99/qalam/blob/main/lib/models/lesson.dart"
click node_database "https://github.com/yussefz99/qalam/blob/main/lib/data/app_database.dart"
click node_repos "https://github.com/yussefz99/qalam/blob/main/lib/data/child_profile_repository.dart"
click node_providers "https://github.com/yussefz99/qalam/blob/main/lib/providers/practice_providers.dart"
click node_model_dl "https://github.com/yussefz99/qalam/blob/main/lib/services/model_download_service.dart"
click node_demo "https://github.com/yussefz99/qalam/blob/main/lib/demo/screens/demo_home_screen.dart"
click node_dev "https://github.com/yussefz99/qalam/blob/main/lib/dev/authoring_screen.dart"
click node_docs "https://github.com/yussefz99/qalam/blob/main/docs/design/README.md"

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_router,node_home,node_practice_screen,node_settings,node_onboarding,node_journey,node_theme,node_widgets toneBlue
class node_practice,node_canvas,node_feedback,node_scoring,node_recognition,node_curriculum,node_assets,node_models,node_database,node_repos,node_providers,node_model_dl toneAmber
class node_demo,node_dev,node_docs toneMint
```

## Components

### App runtime

Flutter app shell, routing, screens, and shared presentation

- [main.dart](https://github.com/yussefz99/qalam/blob/main/lib/main.dart): Flutter entry · Bootstraps the app, theme, and router · `lib/main.dart`
- [App router](https://github.com/yussefz99/qalam/blob/main/lib/router/app_router.dart): Navigation · Central route definitions and flow gating · `lib/router/app_router.dart`
- [Home](https://github.com/yussefz99/qalam/blob/main/lib/screens/home_screen.dart): Screen · Primary landing screen for the app · `lib/screens/home_screen.dart`
- [Practice screen](https://github.com/yussefz99/qalam/blob/main/lib/screens/practice_screen.dart): Screen · Top-level practice entry screen · `lib/screens/practice_screen.dart`
- [Settings](https://github.com/yussefz99/qalam/blob/main/lib/screens/settings_screen.dart): Screen · App settings and preferences screen · `lib/screens/settings_screen.dart`
- [Onboarding](https://github.com/yussefz99/qalam/blob/main/lib/features/onboarding/onboarding_screen.dart): Feature flow · Initial profile setup and first-run experience · `lib/features/onboarding/onboarding_screen.dart`
- [Journey](https://github.com/yussefz99/qalam/blob/main/lib/features/journey/journey_screen.dart): Feature flow · Progression map and learning path visualization · `lib/features/journey/journey_screen.dart`
- [Theme](https://github.com/yussefz99/qalam/blob/main/lib/theme/app_theme.dart): Design system · Shared colors, typography, dimensions, and brand extensions · `lib/theme/app_theme.dart`
- [Shared widgets](https://github.com/yussefz99/qalam/blob/main/lib/widgets/arabic_text.dart): UI primitives · Reusable Arabic text and mascot presentation widgets · `lib/widgets/arabic_text.dart`

### Learning domain

Practice, curriculum, scoring, recognition, and persistence

- [Practice loop](https://github.com/yussefz99/qalam/blob/main/lib/features/practice/practice_screen.dart): Feature subsystem · Handwriting session experience and feedback loop · `lib/features/practice/practice_screen.dart`
- [Stroke canvas](https://github.com/yussefz99/qalam/blob/main/lib/features/practice/widgets/stroke_canvas.dart): Input surface · Captures user ink and stroke input · `lib/features/practice/widgets/stroke_canvas.dart`
- [Feedback panels](https://github.com/yussefz99/qalam/blob/main/lib/features/practice/widgets/feedback_panel.dart): Guidance UI · Tutor, praise, ghost comparison, and mastery celebration · `lib/features/practice/widgets/feedback_panel.dart`
- [Scoring core](https://github.com/yussefz99/qalam/blob/main/lib/core/scoring/letter_scorer.dart): Evaluation engine · Normalization, resampling, tolerance, and letter scoring · `lib/core/scoring/letter_scorer.dart`
- [Recognizer](https://github.com/yussefz99/qalam/blob/main/lib/core/recognition/handwriting_recognizer.dart): ML abstraction · Handwriting recognition interface and ML Kit-backed implementation · `lib/core/recognition/handwriting_recognizer.dart`
- [Curriculum repo](https://github.com/yussefz99/qalam/blob/main/lib/data/curriculum_repository.dart): Content source · Loads lesson and letter curriculum from assets into domain models · `lib/data/curriculum_repository.dart`
- [Curriculum assets](https://github.com/yussefz99/qalam/blob/main/assets/curriculum/letters.json): Static content · JSON lesson and letter definitions · `assets/curriculum/letters.json`
- [Domain models](https://github.com/yussefz99/qalam/blob/main/lib/models/lesson.dart): Learning model · Lesson, letter, progression, and journey state objects · `lib/models/lesson.dart`
- [Local database](https://github.com/yussefz99/qalam/blob/main/lib/data/app_database.dart): Offline storage · Drift-backed persistence for profiles and progress · `lib/data/app_database.dart`
- [Data repos](https://github.com/yussefz99/qalam/blob/main/lib/data/child_profile_repository.dart): Persistence boundary · Child profile and progress repositories bridging UI and storage · `lib/data/child_profile_repository.dart`
- [Providers](https://github.com/yussefz99/qalam/blob/main/lib/providers/practice_providers.dart): State layer · Riverpod providers coordinating UI, repositories, and session state · `lib/providers/practice_providers.dart`
- [Model download](https://github.com/yussefz99/qalam/blob/main/lib/services/model_download_service.dart): Service · Manages on-device recognition model acquisition and availability · `lib/services/model_download_service.dart`

### Demo and tools

Demo flows, authoring utilities, and external presentation assets

- [Demo suite](https://github.com/yussefz99/qalam/blob/main/lib/demo/screens/demo_home_screen.dart): Presentation flow · Scripted showcase journey for watch, trace, feedback, home, and celebration · `lib/demo/screens/demo_home_screen.dart`
- [Dev tools](https://github.com/yussefz99/qalam/blob/main/lib/dev/authoring_screen.dart): Authoring tools · In-app glyph audit and authoring screens for content validation · `lib/dev/authoring_screen.dart`
- [Design docs](https://github.com/yussefz99/qalam/blob/main/docs/design/README.md): External design assets · Presentation and design-system assets supporting the app UI · `docs/design/README.md`

## Connections

- main.dart → App router: boots · App entry hands off to centralized routing
- main.dart → Theme: applies · Global app theme is configured at startup
- App router → Home: routes to · Primary home flow
- App router → Onboarding: gates · First-run onboarding and profile setup
- App router → Practice screen: routes to · Practice entry point
- App router → Journey: routes to · Progress visualization flow
- App router → Settings: routes to · Settings and preferences flow
- App router → Demo suite: routes to · Demo and showcase routes
- Home → Providers: reads state · Home screen consumes app state and progress
- Practice screen → Practice loop: hosts · Practice screen contains the handwriting loop
- Practice loop → Stroke canvas: captures · Ink input and stroke capture
- Practice loop → Feedback panels: shows · Guidance, praise, and celebration UI
- Practice loop → Scoring core: evaluates · User strokes are normalized and scored
- Practice loop → Recognizer: interprets · Optional recognition path for input comparison
- Practice loop → Providers: updates · Session state and progression updates flow through providers
- Providers → Data repos: loads/saves · State layer mediates access to persistence
- Data repos → Local database: persists · Local offline storage for profiles and progress
- Curriculum repo → Curriculum assets: reads · Asset-backed lesson and letter definitions
- Curriculum repo → Domain models: builds · Converts curriculum content into domain objects
- Journey → Providers: reads state · Journey view renders progression from provider state
- Providers → Curriculum repo: uses · Providers combine curriculum with progress state
- Model download → Recognizer: supplies models · Service supports device-side recognition model management
- Dev tools → Curriculum repo: audits · Authoring and glyph tools inspect curriculum content
- Demo suite → Shared widgets: reuses · Demo screens share branded presentation widgets
- Theme → Shared widgets: styles · Shared presentation layer is themed consistently
- Design docs → Theme: informs · Design system docs shape the app visual language