Exalt24/math-problem-generator：面向新加坡五年级的 AI 数学应用题生成器

An AI-powered math word problem generator for Primary 5 students (ages 10-11) aligned with Singapore's Mathematics syllabus.

The hosted copy cannot save problems: its Supabase project no longer exists, so it was left out of the links. Run it locally against a local Supabase (supabase start) as described below.

✨ Features

📚 Syllabus Coverage

Primary 5 topics: Fractions • Decimals • Percentages • Rate • Ratio • Volume • Area • Perimeter • Speed • Distance • Time

🛠️ Technology Stack

🧪 Testing Setup

For assessment and testing purposes

To run the app or the automated test scripts, copy .env.local.example to .env.local and fill in your own Supabase and Google Gemini credentials. The full walkthrough is in Local Setup below.

📦 Local Setup

Prerequisites

• Node.js 20.x or higher
• npm 10.x or higher
• Supabase account (free tier)
• Google AI Studio API key (free tier)

Installation Steps

1️⃣ Clone the Repository

git clone https://github.com/Exalt24/math-problem-generator.git
cd math-problem-generator

2️⃣ Install Dependencies

npm install

3️⃣ Set Up Supabase

1. Create a project at supabase.com
2. Navigate to SQL Editor
3. Run database.sql to create tables
4. Copy Project URL and Anon Key from Settings → API

4️⃣ Get Google Gemini API Key

1. Visit Google AI Studio
2. Click Get API Key
3. Create and copy your key

5️⃣ Configure Environment Variables

cp .env.local.example .env.local

Edit .env.local with your credentials:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
GOOGLE_API_KEY=your_google_gemini_api_key

6️⃣ Run Development Server

npm run dev

7️⃣ Open Browser

Navigate to: http://localhost:3000

🧪 Testing

Manual Testing (Browser)

npm run dev
# Open http://localhost:3000

Test checklist:

• ✅ Generate problems across all difficulty levels
• ✅ Submit correct and incorrect answers
• ✅ Use hint system (3 hints per problem)
• ✅ View answer history
• ✅ Test mobile responsiveness
• ✅ Verify confetti animation on correct answers

Automated API Testing

Five comprehensive test scripts are provided in the /tests folder:

Quick Test: All Difficulties

node tests/test-all-difficulties.js

Generates one problem per difficulty level.

Test Generate API

node tests/test-generate.js [difficulty]
# Examples:
node tests/test-generate.js easy
node tests/test-generate.js medium
node tests/test-generate.js hard

Test Complete Flow

node tests/test-submit.js

Tests generate + submit flow with retry logic for all difficulty levels.

Test Sequential (Reliable)

node tests/test-submit-sequential.js

Slower but more reliable testing with 5-second delays (avoids rate limiting).

Test Single Submission

node tests/test-submit-simple.js <sessionId> <answer>
# Example:
node tests/test-submit-simple.js "abc-123-def-456" 42

Test Hints & History

Test these features manually in the browser UI.

Database Verification

View data in Supabase:

1. Open Supabase Dashboard → Table Editor
2. Check math_problem_sessions for generated problems
3. Check math_problem_submissions for answer submissions
4. Verify difficulty and hints_used columns are populated

Clean database (reset data):

# Run cleanup-database.sql in Supabase SQL Editor

This removes all data while preserving table structure.

📁 Project Structure

math-problem-generator/
│
├── app/
│   ├── api/
│   │   └── math-problem/
│   │       ├── generate/
│   │       │   └── route.ts          # 🤖 Problem generation + hints
│   │       └── submit/
│   │           └── route.ts          # ✅ Answer validation + feedback
│   ├── page.tsx                      # 🎨 Main UI (difficulty, hints, history)
│   ├── layout.tsx                    # 📐 Root layout
│   └── globals.css                   # 💅 Styles + animations
│
├── lib/
│   ├── gemini.ts                     # 🧠 AI client configuration
│   └── supabaseClient.ts             # 💾 Database client
│
├── migrations/                       # 🔄 Database migrations
│
├── tests/                            # 🧪 API test scripts (5 files)
│   ├── test-all-difficulties.js
│   ├── test-generate.js
│   ├── test-submit.js
│   ├── test-submit-sequential.js
│   └── test-submit-simple.js
│
├── database.sql                      # 📊 Initial schema setup
├── cleanup-database.sql              # 🧹 Data cleanup script
├── .env.local.example                # 🔐 Environment template
├── LICENSE                           # 📄 MIT License
└── README.md                         # 📖 This file

🚀 Deployment to Vercel

Quick Deploy

1. Push to GitHub (ensure .env.local is gitignored)
2. Import repository at vercel.com
3. Configure environment variables:

   NEXT_PUBLIC_SUPABASE_URL
   NEXT_PUBLIC_SUPABASE_ANON_KEY
   GOOGLE_API_KEY
   

4. Deploy (Vercel auto-detects Next.js)
5. Test production deployment

Deployment URL

Production: none at the moment (see the note at the top).

👨‍💻 Developer

Daniel Alexis Cruz

Full Stack Developer

💼 Relevant Experience

Skills Demonstrated in This Project:

• ✅ Next.js 14 App Router with TypeScript
• ✅ AI integration (Google Gemini API) with prompt engineering
• ✅ Database design (PostgreSQL via Supabase)
• ✅ RESTful API development
• ✅ Mobile-first responsive design
• ✅ Production-ready error handling
• ✅ Systematic testing approach

💡 Implementation Highlights

AI Prompt Engineering

• Problem Generation: Structured prompts ensure Singapore Math alignment and age-appropriate language
• Hints System: Progressive hints that guide without revealing answers
• Feedback Generation: Context-aware, encouraging feedback tailored to student's answer

Database Design

• Sessions Table: Stores problems with difficulty and hints
• Submissions Table: Tracks answers with correctness and hints used
• Foreign Key Relationships: Ensures data integrity

Error Handling

• Retry Logic: Automatic retries for transient API failures
• User Feedback: Clear error messages for all failure scenarios
• Graceful Degradation: Application remains functional during partial failures

Performance Optimizations

• Lazy Loading: Components load on-demand
• Optimistic UI: Instant feedback before API confirmation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📝 Assessment Notes

🎯 Built for: Ottodot Full Stack Developer Assessment

Date: October 2025

Core Requirements ✅

• ✅ Next.js 14 with App Router
• ✅ TypeScript (strict mode)
• ✅ Tailwind CSS styling
• ✅ Google Gemini AI integration
• ✅ Supabase database with RLS
• ✅ Mobile-responsive design
• ✅ Complete user flow tested
• ✅ Production-ready error handling
• ✅ Public GitHub repository
• ✅ Vercel deployment

Optional Enhancements Implemented ✅

• ✅ Difficulty Levels: Three tiers (easy/medium/hard)
• ✅ Hints System: Progressive AI-generated hints
• ✅ Answer History: Track all submissions
• ✅ Enhanced UX: Confetti, animations, accessibility
• ✅ Comprehensive Testing: 5 test scripts + manual QA
• ✅ Database Migrations: Systematic schema management

Built with ❤️ for Singapore Primary 5 students

⭐ Star this repo if you found it helpful!