FractionQuest: Interactive Math Learning

[![]](https://deploy.workers.cloudflare.com/?url=${repositoryUrl})

FractionQuest is an interactive, educational web application designed for primary school students to master Addition and Subtraction of Fractions. Built as a modern, interactive slide deck mimicking Slidev, it combines visual learning aids (SVG scaffolding), text-to-speech (TTS) guidance, and step-by-step mathematical explanations. The core features include a custom Slide Engine with React and Framer Motion, dynamic SVG fraction visualizers (Pie and Bar models), vertical fraction rendering, and browser-native TTS for voice-guided lessons.

Key Features

• Slide-Based Learning Journey: Cinema-mode layout with 16:9 responsive stage, navigation controls, progress bar, and smooth transitions.
• Visual Scaffolding: Dynamic SVG pie charts and bar models for concrete fraction visualization (like/unlike denominators).
• Voice Guidance: Integrated browser SpeechSynthesis API with TTS toggle for read-aloud explanations.
• Pedagogical Flow: From basic concepts → like denominators → unlike denominators with equivalence visuals.
• Responsive & Accessible: Mobile-first design with high contrast, keyboard navigation, and touch-friendly controls.
• Views:
  • Landing: Playful hero with "Start Lesson" CTA.
  • Lesson Player: Core slide deck with TTS and interactive aids.
  • Summary: Completion screen with badges.

Tech Stack

• Frontend: React 18, TypeScript, Vite, React Router
• UI/Design: Tailwind CSS 3, shadcn/ui, Framer Motion (animations), Lucide React (icons)
• State & Data: Zustand, TanStack Query
• Audio: Native Web Speech API (TTS)
• Deployment: Cloudflare Pages + Workers (serverless API)
• Utils: clsx, tailwind-merge, Zod (validation), Sonner (toasts)
• Dev Tools: ESLint, Bun

Quick Start

1. Clone & Install:

   git clone <your-repo-url>
   cd fraction-quest
   bun install

2. Development:

   bun dev

   Opens at http://localhost:3000.

3. Build:

   bun build

Usage

• Landing: Welcome screen → Click Start Learning.
• Lesson Player: Navigate slides (Prev/Next/Scrubber), toggle TTS (🔊 icon), visualize fractions.
• No Backend Needed: Fully client-side with static lesson data.
• TTS Voices: Uses browser defaults (Chrome/Edge recommended); toggle for mute.

Example lesson flow:

1. Review fractions → Add like denominators (visual merge) → Subtract → Unlike denominators (find common, equivalence).

Development

• Routing: Edit src/main.tsx (createBrowserRouter). Use <Link> for navigation.
• Components: Leverage shadcn/ui (@/components/ui/*). Custom: Fraction visualizers in lesson slides.
• State: useLessonStore (Zustand) for slide index, audio state.
• Lesson Data: Edit static LessonDefinition TS object.
• Linting: bun lint
• Theme: Dark/Light toggle (useTheme hook).

Hotkeys:

• Arrow keys: Prev/Next slide
• Space: Play/pause TTS

Deployment

Deploy to Cloudflare Pages + Workers in one command:

bun deploy

Uses Wrangler under the hood. Configured in wrangler.jsonc and wrangler.toml.

[![]](https://deploy.workers.cloudflare.com/?url=${repositoryUrl})

Custom Domain: Update wrangler.jsonc → bun deploy.

Preview: bun preview

Project Structure

src/
├── components/     # UI (shadcn/ui + custom: SlideDeck, FractionPie)
├── hooks/          # Custom (useTTS, useLessonStore)
├── lib/            # Utils (cn), error handling
├── pages/          # Routes (HomePage.tsx → Landing)
└── main.tsx        # Router entry
worker/             # API routes (Hono)

Roadmap

• Phase 1: Slide Engine, TTS, SVG visuals, full lesson content (✅ Complete).
• Phase 2: Drag-and-drop exercises, gamification (points, badges).

Contributing

1. Fork & PR.
2. Follow ESLint/TypeScript standards.
3. Test responsiveness & TTS cross-browser.

License

MIT License. See LICENSE for details.

---

Built with ❤️ for educational excellence. Questions? Open an issue!