yussefz99/qalam

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.