ZenMath

Offline maths practice and learning app with performance tracking, streak management, and local evaluation.

Overview

ZenMath provides an offline math training environment. The application runs without an internet connection, storing all user records, sessions, and statistics locally on the device.

• Package ID: com.akashiverse.zenmath
• Target Framework: Flutter 3.44.0 (Stable)
• Database Engine: Isar (NoSQL embedded local store)
• Deployment Model: 100% Cloud CI/CD via GitHub Actions

---

Core Features

• Practice & Play Modes: Interactive arithmetic problem sets covering multiple skill levels.
• Evaluation & Session Summary: Instant breakdowns of accuracy, speed, and question-level responses.
• Progress Tracking & Streaks: Continuous tracking of daily practice goals, active streaks, and historical milestones.
• Visual Analytics: Interactive performance curves and topic breakdowns powered by fl_chart.
• Zero Cloud Dependency: Complete offline operation with zero data sent over the network.
• Theme & UI Preferences: Custom theme switches and configurable session parameters.

---

Tech Stack

Layer	Technology
Framework	Flutter (Dart SDK ^3.0.0)
State Management	Flutter Riverpod
Navigation	GoRouter
Local Storage	Isar Database, SharedPreferences
Data Visualisation	FL Chart
Typography	Google Fonts

---

Architecture & Directory Layout

The codebase follows a modular feature-first structure:

lib/
├── core/                  # Shared utilities, common widgets, and theme definitions
│   ├── theme/
│   ├── utils/
│   └── widgets/
├── data/                  # Isar data source and persistence models
│   ├── models/            # Schema models (DailyProgress, SessionScore, TopicStats)
│   └── isar_service.dart  # Isar database initialization and query handlers
├── features/              # Feature modules (UI + presentation logic)
│   ├── history/           # Completed session logs and history views
│   ├── play/              # Interactive problem runs
│   ├── practice/          # Topic configuration and practice flows
│   ├── results/           # Post-session evaluations and breakdowns
│   ├── settings/          # Application configuration and preferences
│   ├── splash/            # Startup sequence
│   └── stats/             # Visual analytics and charts
├── providers/             # Riverpod state providers (DB, progress, streak, theme)
└── main.dart              # Entrypoint and app bootstrapping

---

Cloud Build & Release Workflow

This repository relies on a cloud-based continuous integration pipeline. Local Flutter or Dart installations are not required.

+--------------------+        +--------------------+        +--------------------+
| Local Workspace    |  --->  | GitHub Repository  |  --->  | GitHub Actions CI  |
| (Edit in lib/)     |        | (git push)         |        | (Cloud APK Build)  |
+--------------------+        +--------------------+        +--------------------+
                                                                      |
+--------------------+        +--------------------+                  v
| Physical Device    |  <---  | Release APK        |  <---  +--------------------+
| (adb install)      |        | (gh download)      |        | GitHub Release     |
+--------------------+        +--------------------+        +--------------------+

Prerequisites

• git
• gh (GitHub CLI authenticated via gh auth login)
• adb (Android Debug Bridge for device deployment)

Development Steps

1. Commit and Push Changes:

   git add .
   git commit -m "feat: your change summary"
   git push origin main

2. Monitor Build: GitHub Actions automatically builds the release artifact.

   gh run list -L 1
   gh run watch <run_id> --exit-status

   To review errors on a failed run:

   gh run view <run_id> --log-failed

3. Install on Device: Connect an Android device with USB debugging enabled, then execute:

   ./update_app.sh

---

Troubleshooting

• Signature Mismatch (INSTALL_FAILED_UPDATE_INCOMPATIBLE): Remove the existing package before re-installing:

  adb uninstall com.akashiverse.zenmath
  ./update_app.sh

• Launch Application via ADB:

  adb shell monkey -p com.akashiverse.zenmath -c android.intent.category.LAUNCHER 1