MathMirror: Adaptive AI Math Practice

Inspiration 💡 Math practice can often feel repetitive and disconnected from a student's real-world interests. We wanted to build a bridge between the foundational math concepts students need to learn and the topics they actually want to think about. We asked ourselves: What if every math problem was dynamically tailored to a student's favorite hobbies, whether that's space exploration, dinosaurs, or video games? We were inspired by the potential of LLMs to generate highly personalized educational content on the fly, keeping students engaged and excited to practice.

What it does 🚀 MathMirror is an adaptive, AI-powered math practice platform that features a dual interface for both Students and Teachers.

For Students: They input their grade level, select a math topic (like Fractions or Geometry), and type in their personal interests (e.g., "Space"). The app instantly uses the Gemini API to generate a custom quiz featuring word problems merged with their interests! When they answer correctly, the difficulty scales up. When they struggle, the app provides helpful explanations and scales the difficulty down. Completing a quiz rewards them with a fun, gamified confetti celebration! For Teachers: A dashboard tracks the student's progress in real-time, displaying their average score, accuracy, total problems solved, and areas of strength or weakness, giving educators actionable insights into where students need the most help. How we built it 🛠️ We built the frontend as a Single Page Application using React (Vite) and TypeScript, stylized with custom CSS and Lucide React icons for a clean, modern, and engaging user interface.

The backend is an Express.js serverless function that interfaces directly with the Google Gemini API (gemini-2.5-flash). We engineered structured prompts to ensure Gemini consistently returns perfectly formatted JSON arrays of math problems, complete with distractors (wrong choices), correct answers, step-by-step explanations, and dynamic difficulty adjustments.

Finally, we deployed the entire full-stack application seamlessly using Netlify, utilizing Netlify Functions to securely host our Express backend without exposing our API keys.

Challenges we ran into 🧗‍♂️ Our biggest technical hurdle was deploying a full-stack Node.js/Express app alongside a Vite frontend in a serverless environment. Initially, we faced 502 Bad Gateway and Runtime.ExitError crashes on Netlify because our Express dev server was trying to bind to local ports within the Lambda function. We solved this by completely decoupling the local development server from the Express route definitions, allowing Netlify Functions to consume the Express app statelessly.

Additionally, we had to carefully handle the Gemini API's output. Sometimes the LLM would wrap the JSON response in markdown code blocks (json ... ). We implemented robust regex parsing to strip any markdown wrappers before parsing the JSON, ensuring the app never crashed due to a malformed response.

Accomplishments that we're proud of 🏆 We are incredibly proud of the adaptive difficulty engine. It is extremely satisfying to see the Gemini AI dynamically scale the complexity of a word problem up or down depending on how the student performs, all while keeping the storyline (like astronauts or dinosaurs) completely consistent. We are also proud of successfully resolving our serverless deployment architecture, resulting in a lightning-fast, production-ready app.

What we learned 🧠 We learned a massive amount about prompt engineering for structured data. We discovered that clearly defining the expected JSON schema and utilizing Gemini's responseMimeType: 'application/json' configuration significantly improved reliability. We also deepened our understanding of serverless architectures and how to transition a traditional Express app into a stateless Lambda function on Netlify.

What's next for MathMirror 🔮 In the future, we plan to add:

Authentication & Classrooms: Allowing teachers to create distinct classrooms and invite students via codes. Deeper Gamification: Adding badges, streaks, and unlockable avatars based on the student's interests. Multilingual Support: Using Gemini to instantly translate math problems into the student's native language for ESL learners.