ArcaneMath

ArcaneMath - A low-code, AI-powered math studio where teachers and students summon interactive GeoGebra activities by chatting with Gemini, then play, share, and climb the ranks.

Comment

Inspiration

Math classrooms have a content problem dressed up as an engagement problem. GeoGebra is genuinely magical — you can show a sine wave bend under a phase slider, or a circle's area emerge from $n$ wedges as $n \to \infty$ — but building those visualizations means learning a command language most teachers don't have time for, and most students never see.

Meanwhile, the games students do spend hours inside (we're looking at you, League of Legends) are masterpieces of feedback, ranks, and that one more match loop. We kept asking: what if learning $y = mx + b$ felt less like a worksheet and more like queueing into a ranked match in the Arcanum of Numbers?

ArcaneMath is our answer — Gemini does the hard part of authoring, GeoGebra does the math, and a Hextech-styled UI makes the whole thing feel like a game worth opening.

What it does

ArcaneMath turns a sentence into a working math activity, then turns that activity into something you can play.

  • Studio (the authoring loop). Type "Show a circle divided into equal slices using a Denominator slider (1–12). A Numerator slider shades that many slices blue. Display the fraction as a label." Gemini returns a full GeoGebra construction — sliders, named sectors, conditional visibility, fraction text — and the embedded applet renders it live. Tweak it in plain English and it patches itself.
  • Self-healing constructions. When GeoGebra rejects a command, the frontend ships the failures back to Gemini's repair endpoint, which rewrites only what broke while preserving the original teaching intent. The author never sees the syntax error.
  • Auto-generated descriptions. Hit publish and Gemini reads your construction, infers the underlying concept, and writes a 350–450 word, GitHub-flavored Markdown explainer with prerequisites, intuition, and try-this bullets — so every activity ships with a real lesson, not just a tagline.
  • Play mode (the student loop). Activities convert into 3–5 multiple-choice conceptual questions Gemini generates from your actual sliders and objects. Wrong answers are common misconceptions, not filler.
  • Arcane AI tutor. A side chat that knows your current activity and answers in plain language — "if I increase the slope $m$, what happens to the line?" — without ever leaking GeoGebra syntax.
  • Library, leaderboard, profile. Save, browse, share, and see who's topping the ranks across the Arena.

How we built it

Backend

A small Express 5 server that wraps Google's @google/genai SDK with a few specialized endpoints:

  • POST /api/generate → Gemini 2.5 Pro, temperature 0.1, returns strict JSON { commands, settings }. The system prompt is a battle-hardened spec sheet of ~24 GeoGebra rules (uppercase point names, no reserved identifiers like radius / rad / pi, Cartesian over polar, Sector over Polygon for fraction wedges, mandatory xAxisStep: 30 and xAxisUnit: "°" for any trig, no Sequence for styled objects, etc.) plus five worked few-shot examples covering phase sliders, fraction circles, and slider-driven implicit circles.
  • POST /api/repair → Gemini 2.5 Flash with the same rule set plus the failed lines, returns a corrected full construction.
  • POST /api/describe → Markdown lesson generator with a strict heading template and a 300-word minimum.
  • POST /api/challenge → 3–5 MCQs in application/json mode with conceptual-not-syntactic constraints.
  • POST /api/tutor → conversational tutor with last-8-turn history, answers grounded in the activity's commands.

A retry helper transparently falls back from Pro → Flash on 503s, and every Gemini response is JSON-stripped of stray triple-backtick fences before parsing.

Frontend

  • React 18 + Vite + Tailwind, with shadcn/Radix primitives, Framer Motion micro-interactions, and a custom Hextech component library (Backdrop, ParticleField, Crest, GoldButton, EyebrowDivider, HexAvatar) that gives the whole app the gold-and-teal League/Arcane look.
  • A GeoGebraStage component embeds the GeoGebra applet, executes commands one by one, captures failures, and pipes them into the repair endpoint.
  • React Router for the page graph: Home, Activities, Studio, Create, Activity/:id, Activity/:id/play, Library, Leaderboard, Slope.
  • Firebase for auth and persistence; React Query for server state; React Hot Toast and Sonner for the surfaces in between.

Prompt engineering as a first-class artifact

The single biggest unlock was treating Gemini's system prompt like production code — versioned, commented, and stress-tested against a corpus of activities (sine phase, slope-intercept, fraction circles, transformation drills). Every footgun we hit became a numbered rule.

Challenges we ran into

  • GeoGebra's silent failures. Naming a point centerPoint doesn't error — it just creates a vector, and then Circle(centerPoint, 5) quietly does nothing. We learned the rules the hard way (uppercase = Point, lowercase = number/vector) and codified them in the system prompt.
  • The radius trap. GeoGebra silently treats rad as the radians unit, so radius = Slider(...) becomes a malformed equation. We banned a whole list of reserved names: radius, rad, pi, e, c, l, i.
  • Trig axes. Out of the box, plotting $\sin(x)$ gives you a sad squiggle from $-10$ to $10$ in radians with no useful gridlines. We made degree-mode trig — sin(x°), xAxisStep: 30, xAxisUnit: "°", range a multiple of $360$ — mandatory and unconditional, even if the user didn't ask.
  • Sequences vs. styling. Sequence(Polygon(...), k, 1, n) is ergonomic but its results can't be colored, filled, or conditionally shown. For the fraction-circle activity we had to teach the model to unroll the loop into individually-named wedge1…wedgeN and ray1…rayN to keep SetColor and SetConditionToShowObject working.
  • JSON drift. Gemini occasionally wraps responses in triple-backtick fences despite being told not to. We strip fences before parsing and built a generateWithRetry that falls back from Pro to Flash on parse or 503 failures.
  • Latency vs. quality. Pro gives the best constructions; Flash is twice as fast. We route generation to Pro and everything else (repair, describe, challenge, tutor) to Flash — quality where it matters, speed where it's felt.

Accomplishments that we're proud of

  • You can describe a fraction-circle activity in one sentence and get a working, styled, slider-driven model in under 10 seconds. That used to be a 200-line GeoGebra session.
  • A self-healing pipeline — authors literally never see a GeoGebra syntax error.
  • Activities ship with real lessons, not stubs. The Markdown auto-description is something we'd actually hand a student.
  • A frontend that feels like a game. The Hextech kit makes a math tool that students don't want to close.
  • Production-grade prompt engineering: ~24 numbered GeoGebra rules + 5 few-shot examples that survive contact with real users.

What we learned

  • LLMs are excellent compilers from natural language to constrained formal languages — if you treat the system prompt like a spec, give it a JSON schema, and bake in worked examples for the cases it gets wrong.
  • Self-healing > better generation. A Pro pass that's right 90% of the time plus a Flash repair pass that fixes the other 10% beats grinding the prompt to 95% with twice the latency.
  • Math content has structural footguns that a generic "use GeoGebra" prompt can't solve. Domain rules (uppercase points, degree-mode trig, named wedges) had to be encoded explicitly.
  • Aesthetic is pedagogy. The same activity behind a Hextech UI gets way more one-more-go energy than the same activity behind plain Bootstrap.

What's next for ArcaneMath

  • Curriculum-aligned activity packs with teacher dashboards — assign, track mastery, export grades.
  • Multiplayer ranked mode — head-to-head MCQ duels off the Play screen, with ELO and seasonal banners.
  • Voice-driven authoring. Speak a lesson, get a lesson.
  • Step-by-step solver overlay. Arcane AI shows worked steps, not just answers, and highlights the moving slider as it explains.
  • 3D constructions via GeoGebra's 3D view — we already pull in Three.js for the Hextech effects, so extending to a true 3D applet is the next milestone.
  • Marketplace. Authors get attribution and a leaderboard of their own.

Built With

  • canvas-confetti
  • command-api)-auth-&-data:-firebase-(auth
  • cors-ai:-google-gemini-2.5-pro-(generation)-and-gemini-2.5-flash-(repair-/-describe-/-challenge-/-tutor)-via-@google/genai-math-engine:-geogebra-(embedded-applet
  • css-frontend:-react-18
  • custom-hextech-component-library-backend:-node.js
  • dotenv
  • express-5
  • firestore)-tooling:-eslint
  • framer-motion
  • html
  • html2canvas
  • jspdf
  • jsx
  • languages:-javascript-(es-modules)
  • lucide
  • postcss
  • radix-ui-/-shadcn
  • react-hook-form-+-zod
  • react-hot-toast
  • react-router
  • recharts
  • sonner
  • tailwind-css
  • tanstack-react-query
  • three.js
  • typescript-(jsconfig)
  • vite-6
Share this project:

Updates