Math Quest: Interactive 3D / AR maths learning (Let's make learning math Fun 😄️)

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

Well, at times learning is hard for some people, especially Mathematics (and maybe Physics 😅️ or History because I cannot seem to remember years correctly ) but we'll focus on some math ( before I start complaining about my memory during History exams 😅️). Most people would love to learn with visuals in order to make it easier and maybe after a while they will pay for it with our local currency ( Kenya ). Three Dimensional models help interactivity and learners can get detailed experience especially for spheres and 3d shapes. 3D artists can also get some coffee( payment appreciation) for their contribution to better models. Learners can explore these models through Augmented Reality devices for it to be fun and understand the concepts. My motto in this website is that

Math does not need to be textbook serious to be understood. Learning should be a fun and interactive experience.

Math Quest is a mobile-first web app that teaches geometry through interactive 3D solids, like spheres, cylinders, cones, pyramids, hemispheres, cubes and some geometrical calculations on three dimensional models.
Learners read a short explanation ( there's also a voice narrator ), explore a diagram and a rotatable model (with optional AR on supported phones), answer a quick check, and request tutor hints when stuck.
Ten lessons are free; extra content unlocks after a confirmed M-Pesa payment. Accounts use email OTP ( One Time Password ) to reduce fake sign-ups ( there are many bots these days and also fake mail generators , we don't want our database to be filled with those).
An admin dashboard tracks users, verified payments, revenue, voice-service errors and approvals.
A public artists gallery lets 3D creators submit model links and share PayPal or M-Pesa details for tips.
The website is built with Next.js, MongoDB Atlas as a database , Safaricom Daraja for payment which is a local means of payment because I would first start locally although Stripe payment is also not available for local developers and deployed on Render.
Currently I am using publicly available three dimensional models from here but I have credited the authors within the website as per their licenses.

Note for any developer who uses public resources just like me: For these public models , licenses should be checked in order to use resources because some creators prohibit using their resources for commercial purposes and also most of them require crediting for their work. There are different types of licenses out here so it will only take approximately 20 minutes to learn about them and the different media that use them (even GitHub uses them btw). This will save you from any lawsuits if you have a website especially one you are using to gain income. Let's not make a small hustling website bring you losses because you do not check for licenses. Every media you use should be carefully analyzed and credited if it's not yours. Last but not least it is polite to credit an artist.

The problem

• Learners Of any age ( we learn every day, no age limit ) need geometry they can See and Move — not only flat textbook diagrams. They need to be able to visualize the concepts to get a better understanding
• 3D artists need a way to showcase their skills. There are little opportunities for three Dimensional artists especially locally and this provides a way of making their talent known and be able to provide 3D art or AR (Augmented reality) in a fun and learning manner. There are few public geometric models out here and it was hard for me to find what to embed but with this, many artists can create their art to be used for learning.
• 3D artists also need a hustling website or gig so this might be a good start for them to show case their skills and they would be able to get paid and sign a contract with the admin if they want more job security than just a buy me coffee button

Who's using it

1. Pupils & parents - inspect cubes, spheres, and related shapes through on-page diagrams and optional AR-capable models, then answer questions and get hints.
2. Teachers / tutors - analytics surface for registrations, revenue, voice failures , and a moderated artist registry that stores metadata and tip contacts
3. 3D artists - Submit models and get tips (PayPal / Mpesa)

Features map

  Math Quest Landing page
      │
      ├── Learning
      │     ├── 10 free 3D geometry lessons
      │     ├── 2 paid advanced lessons
      │     ├── Interactive diagrams
      │     ├── GLB models + AR (where supported)
      │     ├── Quiz + mastery progress
      │     └── Step-by-step tutor hints
      │
      ├── Access & trust
      │     ├── Email OTP registration
      │     ├── Session auth (JWT cookie)
      │     └── M-Pesa unlock (confirmed only)
      │
      ├── Community
      │     ├── Artists submit model links
      │     └── Buy-me-a-coffee (PayPal / M-Pesa)
      │
      └── Ops
            ├── Admin: users, revenue, payments
            ├── Failure analytics
            └── Artist approve / reject

Demo

Here is a link from Render : https://mathquest-hlil.onrender.com/

Code

Here is my code, I have included an example of what is in my .env (with no real secrets of course) file for anyone to try out and run on local to at least view the admin dashboard on local . My email is the only admin on Render and adding anyone else is not recommended so it's better to run on local. The instructions to run are on the GitHub repo but feel free to ask questions , raise issues and try to make pull requests if you need a feature request. I would like to try to add a feature request from someone.

taylorhelene / Mathquest

Week 2 submission

Math Quest

Interactive 3D geometry lessons in the browser — rotate models, optional AR, tutor hints, email OTP sign-up, M-Pesa unlock, and an admin dashboard with Gemma briefing.

Route	What
/	Landing page
/learn	Lessons
/artists	3D artist gallery + tips (PayPal / M-Pesa)
/admin	Analytics, payments, AI logs, approvals

Stack: Next.js 14 · TypeScript · MongoDB Atlas · Safaricom Daraja · Render

---

Install

Fork the repo

git clone <your-repo-url>
cd math-quest
cp .env.example .env.local
# fill in at least JWT_SECRET (and MONGODB_URI for accounts/payments)

npm install
npm run dev

Open http://localhost:3000.

Command	Purpose
npm run dev	Local development
npm run build	Production build
npm start	Run production build

---

Environment

Copy .env.example → .env.local (local) or set the same keys on Render. Add your keys.

---

Admin

Sign in with an email listed in ADMIN_EMAILS, then open /admin.
Gemma (if configured) summarises highlights, what to…

View on GitHub

How I Built It

1. I used Ollama in locally and installed Gemma model
2. I used local Gemma for improving my local project files
3. I used Gemma to provide hints for learners in the project using API from Google AI studio.
4. I used ElevenLabs text-to-speech free credit for audio for the readers who also need articulation. Some other educational voice ID was not free so I used the free one provided in Developers dashboard
5. I used Gemma-powered admin briefing that summarizes highlights, issues to check, and pending approvals using API from Google AI studio.
6. I use MongoDB to preserve lesson history , API errors and user data
7. I hosted the project on Render and used AI insights to check build errors

Project Tech stack

Layer      | Choice
--------------------------------------------------------------
Frontend   | "Next.js 14 (App Router), TypeScript, CSS", Gemma
3D / AR    | Google <model-viewer> + .glb
Backend    | Next.js API routes
Database   | MongoDB Atlas
Payments   | Safaricom Daraja (STK Push + Query + callback)
Auth       | Email OTP + JWT cookie
Audio      | ElevenLabs + browser fallback
Hosting    | Render
_______________________________________________________________

List of screens and controls

Landing page

• Header — top bar of the site
• Start learning — opens the learning page
• 🎨 Artists gallery — opens the artists page
• Feature cards — information only
• Footer — links and site info at the bottom

Header

• Theme button — switches light / dark theme
• Sign in — opens the auth modal
• Sign out — ends the session; progress no longer saves to the cloud
• Unlock with M-Pesa — opens the M-Pesa payment modal
• Admin (admin users only) — opens the admin dashboard

Lessons list

• Free lesson row — opens that lesson (content, diagram, 3D model, quiz)
• Paid / locked lesson row — asks for M-Pesa unlock if not paid; opens the lesson if paid or admin
• Progress marks — show saved attempts / mastery when signed in

Lessons workspace

• Lesson title & summary — topic overview
• Lesson body text — teaching content
• Diagram (LessonVisual) — SVG preview of the solid
• 3D model viewer — drag to rotate, scroll to zoom (background always dark)
• View in your space — opens AR on supported phones
• Model credit line — shows 3D model author / licence
• Play audio — speaks lesson text (ElevenLabs, or browser voice if the API fails)
• Answer options — choose one multiple-choice answer
• Check answer — marks right/wrong, shows explanation, saves progress if signed in
• Get a hint — Gemma tutor hint (up to 3 levels)

Footer

• Home — go to home
• Lessons — lessons page
• Artists gallery — go to artists gallery
• Admin — go to admin dashboard
• Submit a 3D model — go to artists submit form

Auth modal

• Sign in — log in with email + password (if email is verified)
• Need an account? Register — switch to the registration form
• Name / Email / Password — account fields
• Send verification code — saves the account and sends a 6-digit OTP email (or logs the OTP if Resend is not set)
• Verification code (OTP) — enter the 6-digit code
• Verify & continue — confirms OTP, signs you in, closes the modal
• Resend code — sends a new OTP (expires in 10 minutes)
• Back to sign in — return to the login form
• Already registered? Sign in — switch to the login form

Pay modal (M-Pesa)

• M-Pesa phone number — number that receives the STK PIN prompt
• Pay with M-Pesa — starts STK Push; order stays pending until success
• I’ve paid — check status — checks Daraja/DB; unlocks only if payment completed
• Close — closes the modal without unlocking

Artists page — gallery

• ← Back to Math Quest — go to home
• Open 3D model — opens the model URL in a new tab
• ☕ Buy me a coffee (PayPal) — opens PayPal donate / paypal.me for that artist
• 📱 M-Pesa — copies the M-Pesa number for Send Money

Artists page — submit form

• Display name — public artist name
• Email — contact for moderation
• Model title — name of the model
• Model URL — public https link to .glb or model page
• Bio (optional) — short description
• License (optional) — e.g. CC-BY, CC0
• PayPal — email or paypal.me for tips
• M-Pesa number — phone for tips (at least one of PayPal or M-Pesa required)
• Submit for review — saves as pending until an admin approves

Admin — Gemma briefing

• Summary — short overview of platform health
• Highlights — key stats (users, revenue, AI)
• What to check — issues to review (pending pay, OTP, errors)
• Approvals pending — artist queue status
• Open Artists & tips — switches to the Artists tab

Admin — tabs

• Overview — KPI cards + metrics table
• Payments — confirmed M-Pesa payments table
• Users — recent users (verified / paid)
• AI services — Gemma + ElevenLabs event log table
• Artists & tips — submissions + PayPal/M-Pesa + approve/reject

Admin — artist actions

• Approve — publishes models to the public gallery
• Reject — keeps the model off the public gallery
• ← Home — go to home
• Lessons — go to the lessons page

Why Does Open Innovation Matter?

Open Innovation is the general concept of the project as I am using the open source AI to build a project from scratch and to ensure it runs smoothly and tries to solve a current problem which is providing financial ease for 3D artists who need jobs and also making it easier for learners to get key concepts. The product is designed for real-world constraints in East Africa—mobile browsers, intermittent connectivity to external APIs, and MPesa as the primary payment . Free content lowers the barrier to entry; paid lessons unlock only after Mpesa payment.
The project is created based on open source models and it makes these possible :
Access: Runs in the browser on shared or low-end phones—no app install.
Local payments: M-Pesa matches how families in Kenya already pay.
Pedagogy: 3D + hints support spatial thinking better than static notes alone.
Integrity: OTP reduces bot sign-ups; only confirmed payments unlock content.
Creators: Artists can share better models and receive tips without the app storing huge binary files.

Challenges faced

I did face some challenges during the project development which was solved by Gemma locally:

• User paid, but the dashboard still showed pending and paid lessons stayed locked.This was because I was treating ResponseCode: "0" as “paid” — that only means the prompt was sent, not that PIN succeeded. Weak handling of final codes caused a problem and Gemma was using a wrong reference so I updated the current documentation reference:

ResultCode: "0" → real success → unlock
1032 → cancelled by user → failed
1037 → timeout / user unreachable → failed

• ElevenLabs voice lesson audio failed at first; within the analytics tab in the developer dashboard in the ElevenLabs website : https://elevenlabs.io/app/developers , it showed 402 error. The cause was missing credits / plan limits on the educator's voice ID I wanted and I did not realize it needed to be paid for. I used the free voice ID that was in the Developer's dashboard.

• Register modal sent a code to my email when testing, but the interface didn’t clearly show an OTP modal that was supposed to pop up. The cause was a pop up extension blocker was preventing the modal from showing

• next build failed on Render with:
  

@typescript-eslint/no-namespace 
@typescript-eslint/no-explicit-any 

Cause was strict next/typescript rules treat many normal patterns as errors, which fail the build.
Gemma relaxed rules. Strict ESLint + next build will block shipping unless rules or ignoreDuringBuilds are set.

• My render website is not loading the models as fast as I want, I have not solved this yet because it may be a platform issue

Finally answering why why open innovation matters

The business is low cost due to running Gemma as a hint provider instead of getting an actual tutor. The customer's data is not shared on any platform , it is private and stored on MongoDB Atlas. I can always change references to my local model for precise answers. I am using Gemma as a tutor ,hint provider and dashboard summarizer and it is a free API so I am not locked on prices currently.

My Agent Session

It is not possible to add logging for a free API in Google AI studio

My First User

I am the only tester currently and I paid while testing 😅️. But no real user currently though, I will try to get one within the week.

Prize Categories

• Best Use of Render
• Best Use of Gemma
• Best Use of ElevenLabs
• Best Use of MongoDB Atlas