MathPulse AI

The AI-powered math studio for Filipino Senior High STEM.
Personalized lessons. AI tutor. Quiz battles. Real-time class analytics.
Installable PWA + native Android, running on Firebase.

Live Demo • PWA • Download • Features • API • Contributing

Click the image above to open the live app on mathpulse-ai-2026.web.app — sign in with a 1-click demo account, no setup required.

Login mascot tracks the cursor — move left to right and the bot looks left to right.

What is MathPulse AI?

MathPulse AI is an installable, gamified learning platform for SHS math — a free, repository-owned alternative to generic tutoring apps, purpose-built around the DepEd Strengthened SHS curriculum. Students get diagnostic assessments, AI-generated study plans, RAG-grounded lessons, and a 24/7 AI tutor. Teachers get at-risk detection and class analytics. Admins get platform-wide oversight and AI cost monitoring.

• Curriculum-first — modules load directly from DepEd SHS guides (General Math, Business Math, Statistics & Probability); RAG lesson generation cites real teaching-module sources
• L.O.L.I. AI tutor — Logical Operations & Learning Intelligence, powered by DeepSeek with streaming, continuation repair, and KaTeX math rendering
• Gamified to the core — XP, exponential leveling, 7-day reward cycles, streaks, 12+ achievements, Quiz Battle PvP, leaderboards
• Three role studios — student, teacher, and admin dashboards, each with its own sidebar, metrics, and tools
• Runs anywhere — installable PWA (offline-capable), native Android APK via Capacitor, Docker self-host

---

Try it live

No install, no keys. Open the deploy and pick a demo account:

Open the live app →

Screenshots in this README were captured from that deploy with Chrome DevTools (docs/screenshots/, re-capture anytime with node scripts/capture-readme-screenshots.mjs; login bot GIF with node scripts/capture-login-bot-gif.mjs + ffmpeg).

---

Download

View all binaries →

Android details — Firebase-native (Auth, Firestore, Realtime DB), adaptive launcher icon, hardware back-button handling, edge-to-edge safe-area layout. Full guide: Android Setup & Release Guide.

PWA details — versioned app-shell service worker, offline fallback, conservative caching (no auth/API caching), iOS Add-to-Home-Screen guidance. Full guide: PWA docs.

---

Features

Student studio

Gamified home base: hero greeting with Continue Learning, Start Learning module cards with progress, Competency Matrix radar, Rewards & Achievements, Quiz Battle entry, and live Leaderboards — with the floating L.O.L.I. tutor one tap away.

• Diagnostic Assessments — skill-level evaluation on first login; at-risk subjects shape the whole journey
• Personalized Learning Paths — AI-generated study plans built from weaknesses and priority topics
• Curriculum Modules — DepEd-aligned lessons and quizzes with source citations, search, and subject/quarter/competency filters
• L.O.L.I. AI Chat Tutor — DeepSeek-powered help with smart streaming, continuation detection, completion repair, think-tag stripping, and offline fallback answers
• Quiz Battle — real-time PvP matchmaking over Firebase Realtime Database
• Daily Rewards — 7-day claim cycle (XP boosts, streak shields, hint tokens) with Firestore streak tracking
• Gamification — XP, exponential levels, streaks, 12+ achievements, animated XP toasts, global + section leaderboards
• Grades, Tasks, Profile, Avatar Studio — grade breakdowns, kanban task board, editable profile, unlockable avatar gear
• Notifications & Settings — real-time Firestore notification center, personal preferences, scientific calculator (Alt+K)

Teacher studio

Mission control for a class: headcount, class average, engagement, and at-risk counts up top; AI insight banner calling out students falling behind; class cards with risk badges; calendar + live activity stream on the rail.

• Teacher Dashboard — 12-student overview with AI-generated daily insight and review-student shortcut
• Risk Classification — dual pipeline: DeepSeek structured-output labels + supervised XGBoost/RandomForest scoring with SHAP explanations
• Class Analytics & Topic Mastery — per-student and class-wide metrics, topic performance views, competency tracking
• AI Quiz Maker & Question Bank — import-grounded generation from uploaded class materials
• Smart Data Import — CSV/Excel/PDF class records with AI column detection
• Task Assignment & Calendar — create assignments, track them on the class calendar

Admin studio

Platform-wide command deck: active students/teachers/classes, XP event volume, at-risk alerts, AI-vs-manual activity chart, model success-rate monitor with health check, top-performer mastery cards, and subject breakdowns.

• Platform Overview — students, teachers, classes, XP events, at-risk alerts at a glance
• User & Class Management — create, edit, and manage accounts across all roles
• Content & RAG Manager — administer curriculum content; upload/reingest PDFs into the Chroma vector store
• AI Monitoring — DeepSeek success rate, error counts, retries, per-model cost tracking; runtime profile switching (dev / budget / prod) without redeploys
• Audit Log & System Settings — severity-tagged admin action log, feature flags, maintenance mode

AI models (current runtime)

Runtime routing (backend/services/inference_client.py) dispatches with fallback chains; profiles switchable live from the admin panel. Risk also has a supervised ML path (XGBoost/RandomForest, models/risk_classifier.joblib, trained via /api/predict-risk/train-model).

---

Tech Stack

Frontend

Backend & AI

Infrastructure

---

Getting Started

Prerequisites

• Node.js ≥ 18 · npm ≥ 9 · Python ≥ 3.10
• A Firebase project (console)
• A DeepSeek API key (platform.deepseek.com)

Installation

1. Clone the repository

   git clone https://github.com/Deign86/MATHPULSE-AI.git
   cd MATHPULSE-AI
   

2. Install frontend dependencies

   npm install
   

3. Configure environment variables — create .env.local:

   # Firebase (required)
   VITE_FIREBASE_API_KEY=your_api_key
   VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
   VITE_FIREBASE_PROJECT_ID=your_project_id
   VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
   VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
   VITE_FIREBASE_APP_ID=your_app_id
   
   # DeepSeek API (required for AI features)
   DEEPSEEK_API_KEY=your_deepseek_api_key
   DEEPSEEK_BASE_URL=https://api.deepseek.com
   
   # Backend API (optional — defaults to same-origin /api)
   VITE_API_URL=/api
   VITE_APP_VERSION=1.1.0-curriculum-sot
   
   # Import-grounded generation flags (frontend)
   VITE_ENABLE_IMPORT_GROUNDED_QUIZ=true
   VITE_ENABLE_IMPORT_GROUNDED_LESSON=true
   VITE_ENABLE_IMPORT_GROUNDED_FEEDBACK_EVENTS=true
   VITE_ENABLE_ASYNC_GENERATION=true
   

4. Start the frontend dev server

   npm run dev
   

   Opens at http://localhost:5173.

5. Set up the backend (optional, for AI features)

   cd backend
   pip install -r requirements.txt
   export DEEPSEEK_API_KEY=your_deepseek_api_key
   uvicorn main:app --reload --host 0.0.0.0 --port 7860
   

   Set VITE_API_URL=http://127.0.0.1:8000 when running FastAPI separately, or keep /api behind the Docker/Nginx proxy.

Build & deploy

npm run build                        # → build/
npx firebase deploy --only hosting   # PWA → Firebase Hosting

Backend regression gate

npm run check:backend         # pytest + mypy
npm run check:backend:dev     # mypy only (fast, runs on predev)
npm run check:backend:quick   # critical test file only

---

Architecture

Mapped as a knowledge graph with GitNexus — 573 source files, 16,882 symbols, 26,955 relationships, 580 functional communities, 300 execution-flow chains. Deepest call chains (7–8 steps) run UI → API service → backend route → AI inference → Firestore.

Key patterns — service-layer abstraction (components never touch Firestore directly), discriminated role types (StudentProfile | TeacherProfile | AdminProfile), AuthContext/ChatContext + onSnapshot realtime listeners, async task queue for heavy generation (POST /api/lesson|quiz/generate-async → GET /api/tasks/{id}).

Firestore collections — users/ (role-discriminated), progress/, xpActivities/, achievements/, notifications/, tasks/, chatSessions/, chatMessages/.

Cloud Functions (functions/src/) — diagnostic orchestration, rule-based risk analysis, notification fan-out, remedial quiz building, learning-path engine, IAR scoring, reassessment. Pre-deploy gates (pre_deploy_check.py, startup_validation.py) verify imports, env vars, config parsing, and inference-client init.

MATHPULSE-AI/
├── src/                  # React frontend (components, services, stores, data, features)
├── backend/              # FastAPI (routes/, rag/, services/, tests/)
├── functions/            # Cloud Functions (automations, triggers, scoring)
├── android/              # Capacitor native wrapper
├── datasets/             # DepEd SSHS corpus + Chroma vector store
├── scripts/              # Gates, seeds, model sync, screenshot capture
├── docs/                 # PWA, Android, contracts — plus docs/screenshots/
├── docker-compose.yml  / Dockerfile / nginx.conf / firebase.json

---

📡 API Reference

The FastAPI backend exposes 64 routes across 15+ modules (interactive docs at /docs or /redoc when running):

Math verification pipeline — self-consistency (3 samples, agreement-scored), sandboxed Python code verification, and a low-temperature LLM judge.

---

Gamification System

---

🐳 Docker

docker compose up                 # dev: hot reload frontend + backend
docker compose --profile prod up  # prod: Nginx serving optimized build
docker compose down               # stop

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Conventions — PascalCase components in src/components/, camelCase services in src/services/, shared types in src/types/models.ts, Tailwind utilities (mobile-first), all API calls through src/services/apiService.ts + src/config/env.ts.

---

📄 License

MIT — see LICENSE.

👥 Authors

• Deign86 — GitHub

---