Inspiration
Most AI tutoring tools do the same thing: ask a question, grade the answer, hand back a percentage. But a score doesn't tell a student what they don't understand — it just tells them that they don't. We kept coming back to a simple observation from how real tutors work: the fastest way to find a gap in someone's understanding isn't to test them, it's to have them explain the idea back to you. The moment a student starts explaining glucose production but stumbles on chlorophyll, you know exactly where to help — not just that they're "at 60%." We wanted to build that diagnostic instinct into an AI tutor, instead of another quiz-and-grade app.
What it does
illume asks a student to explain a topic in their own words, rather than answering multiple-choice questions. An AI model then breaks that explanation down concept by concept, identifying specifically which ideas the student has mastered and which ones are still shaky — displayed as "Glow Spots," visual cards that stay dim until a concept is understood. Clicking a dim spot opens a short, analogy-based micro-lesson targeted at that exact gap; once the student confirms they understand it, the spot lights up. When every concept in a topic is lit, illume celebrates the moment instead of just logging a grade. Over time, a dashboard tracks progress across every topic a student has worked on, including a "Concept Constellation" that visually maps mastery using a blur-to-focus effect — blurry dots for shaky concepts, crisp dots for mastered ones.
How we built it
illume is a Next.js App Router application written in TypeScript, styled with Tailwind CSS and a custom design system built on shadcn/ui. The core diagnostic logic lives in a server-side API route that sends the student's topic, question, and explanation to the Groq API, requesting structured JSON output so the response can be reliably parsed into a mastery score, an overall status, and a set of Glow Spots. To keep the diagnostic flow resilient, we built a model fallback chain, so if a larger model is unavailable, the request automatically retries against smaller models rather than failing outright. On the client, Zustand handles state and persists diagnostic sessions to localStorage, which powers both the results view and the dashboard's mastery trend chart, built with Recharts. We designed a signature "Lamp Glow" visual system — CSS radial-gradient glows, a one-shot bloom animation on concept mastery, and blur-to-focus encoding on the dashboard — to make the core mechanic of illume, gaps closing one at a time, visible rather than abstract.
Challenges we ran into
Getting a language model to reliably return the same structured shape every time was harder than expected — models would occasionally wrap JSON in markdown fences or add commentary around it, so we had to build extraction and validation logic on top of the raw API response rather than trusting it blindly. Designing for two very different emotional registers in the same app was also a challenge: the diagnose flow needed to feel encouraging and low-stakes for an 8-to-14-year-old in the middle of getting something wrong, while the dashboard needed to feel credible and data-driven enough that a parent or teacher would trust it. We iterated on the visual language — particularly the dim-to-lit Glow Spot states — until it read clearly as "in progress," not "failed."
Accomplishments that we're proud of
We're proud that the AI in illume is doing real pedagogical work, not just grading — it's identifying specific conceptual gaps and generating targeted analogies to close them, which is closer to how a good human tutor actually teaches. We're also proud of the design system: the Lamp Glow motif, the constellation dashboard, and the Bud mascot with five distinct moods came together into something that feels considered and specific to illume, rather than a generic AI chat wrapper. Getting the full loop working end to end — explanation in, diagnosis out, micro-lesson, mastery, celebration, persisted history — in the time we had felt like a real accomplishment.
What we learned
We learned how much of "good AI UX" comes down to constraining the model's output rather than just prompting it well — structured JSON, validation, and fallback handling ended up being as important as the prompt itself. We also learned that visualizing partial understanding is genuinely hard: it's easy to show right-or-wrong, but showing "you understand three of these four ideas" in a way that feels motivating rather than like a report card took real design iteration. Finally, we learned a lot about designing for a dual audience at once — a single product that has to feel like a friendly guide to an 8-year-old and a credible tool to their parent.
What's next for illume
Our immediate next step is moving from a single-round diagnosis to a multi-round adaptive flow, using the AI's own follow-up suggestions to ask a second, sharper question once an initial gap is found — closer to how a real tutoring conversation unfolds. We plan to add Supabase-backed authentication so progress persists across devices instead of living only in localStorage, and to build dedicated dashboards for parents and educators, including classroom-level views for teachers managing multiple students. Longer term, we want to expand the subject coverage, add progress reports and notifications, and bring illume to mobile so students can diagnose and close understanding gaps wherever they're studying.
Log in or sign up for Devpost to join the conversation.