Inspiration
Middle-school math should feel connected to the world students already know. Kuki Math Quest turns Ethiopian market situations—sharing injera, comparing produce, calculating prices, ratios, and discounts—into a warm bilingual adventure that can keep working when connectivity drops.
What it does
Kuki Math Quest is a full-stack learning game for grades 5–9:
- Students join with a six-character class code; no email is required.
- A playable Phaser Market Quest presents 15 English/Amharic challenges with visual models, hints, explanations, rewards, and accessible HTML controls.
- Published challenge packs are downloaded into IndexedDB, so students can continue offline.
- Answer, hint, and session events are queued locally and replayed idempotently when the connection returns.
- Challenge order adapts to stored skill mastery, while deterministic validation catches equivalent fractions and known misconceptions.
- Teachers create curriculum-aligned assignments, generate a bilingual draft, edit individual challenges, review every item, and explicitly publish.
- A live dashboard reports mastery, answer attempts, learners needing support, misconceptions, assignment activity, and CSV exports.
How we built it
The UI uses Next.js App Router, React, TypeScript, Phaser, and responsive CSS. OpenAI's Responses API can create strict-schema bilingual challenge packs on the server; every response passes an independent runtime validator and falls back to a deterministic reviewed pack if a key, network, or valid result is unavailable.
Cloudflare D1 stores teachers, classrooms, pseudonymous students, assignments, challenge packs, progress events, mastery, and rewards. Ownership checks isolate teacher data. Student bearer tokens, published-assignment checks, primary-key event IDs, and server-side validation protect the sync workflow.
A service worker caches the app shell and game, while IndexedDB stores profiles, downloaded packs, and an offline-first progress queue. The app is packaged and deployed with OpenAI Sites.
Challenges we ran into
The hardest part was making offline play and server truth cooperate safely. We solved it by writing progress locally first, giving every event a stable UUID, accepting retries with INSERT OR IGNORE, and recalculating mastery after sync. We also kept AI generation away from grading: answers are validated deterministically, and content remains invisible to learners until a teacher reviews and publishes it.
Accomplishments we are proud of
- A complete teacher-to-student loop, not just a game screen
- Broad grade 5–9 curriculum coverage with bilingual content
- A real 15-challenge game that remains keyboard and screen-reader accessible
- Offline continuation and duplicate-safe reconnection
- Teacher ownership checks, pseudonymous learners, and no student email requirement
- 19 passing automated checks covering curriculum, rendering, auth failures, generation, publishing, sync, analytics, and CSV export
What's next
We would pilot with Ethiopian teachers, align each strand against locally approved scope-and-sequence documents, add more Amharic voice support and world themes, and use classroom feedback to tune the mastery thresholds and accessibility experience.
Try it
Open the app, choose Use demo class (code KUKI25), and enter Market Quest. The teacher workflow is available at /teacher.
Built With
- cloudflare-d1
- drizzle-orm
- indexeddb
- next.js
- openai-responses-api
- openai-sites
- phaser.js
- react
- service-worker
- typescript