Skip to content

alfredang/phonics-ai

BranchesTags

Repository files navigation

Phonics AI

An interactive, game-based phonics learning web app for ages 9-15. Built with Next.js, Firebase, and AI-powered features using Google's Gemini API.

Live Demo Documentation Next.js TypeScript Firebase Tailwind CSS

Live Demo

https://alfredang.github.io/phonics-ai/

Documentation

View Full Documentation

User guides for learners, teachers, and parents:

Guide Description
Home Overview and quick start
For Learners Student guide - games, XP, achievements
For Teachers Classroom management, student progress tracking
For Parents Link accounts, monitor child's progress
FAQ Frequently asked questions

About

Phonics AI helps students master English pronunciation through a structured learning journey:

  • 5 Learning Worlds: Progress from basic letter sounds to fluent reading
  • 44 Phonemes: Complete coverage of English sounds with IPA notation
  • 4-Phase Lessons: Listen → Practice → Play → Assess
  • Interactive Games: Phoneme Pop, Word Builder, Sound Match, and more
  • Gamification: XP system, achievements, daily quests, and streaks
  • Speech Features: Text-to-speech pronunciation and voice recording
  • Visual Aids: Animated mouth positions for each sound

Tech Stack

Frontend Framework

Technology Version Purpose
Next.js 14.2 React framework with App Router
React 18.3 UI component library
TypeScript 5.0 Type-safe JavaScript

Styling & Animation

Technology Version Purpose
Tailwind CSS 3.4 Utility-first CSS framework
Framer Motion 11.15 Animation library
clsx 2.1 Conditional class names
tailwind-merge 2.6 Merge Tailwind classes

State Management

Technology Version Purpose
Zustand 5.0 Lightweight state management

Backend & Database

Technology Version Purpose
Firebase Auth 11.1 User authentication
Cloud Firestore 11.1 NoSQL database
Firebase SDK 11.1 Firebase client library

AI & Speech

Technology Purpose
Google Gemini API AI-powered features
Web Speech API Text-to-speech & speech recognition

Development Tools

Technology Purpose
ESLint Code linting
PostCSS CSS processing
GitHub Actions CI/CD deployment

Deployment

Platform Purpose
GitHub Pages Static site hosting
Next.js Static Export Build output

Getting Started

Prerequisites

  • Node.js 18+
  • npm or yarn
  • Firebase account
  • Google AI Studio account (for Gemini API)

Installation

  1. Clone the repository

    git clone https://github.com/alfredang/phonics-ai.git
cd phonics-ai

  2. Install dependencies

    npm install

  3. Set up environment variables

    cp .env.example .env.local

  4. Configure Firebase (see Firebase Setup below)

  5. Run the development server

    npm run dev

  6. Open the app

    Visit http://localhost:3000

Firebase Setup

Step 1: Create a Firebase Project

  1. Go to Firebase Console
  2. Click "Create a project"
  3. Enter project name (e.g., phonics-ai)
  4. Disable Google Analytics (optional)
  5. Click "Create project"

Step 2: Register Your Web App

  1. In Firebase Console, click the Web icon (</>)
  2. Enter app nickname: phonics-ai-web
  3. Click "Register app"
  4. Copy the config values shown

Step 3: Enable Authentication

  1. Go to Build → Authentication
  2. Click "Get started"
  3. Enable Email/Password provider

Step 4: Create Firestore Database

  1. Go to Build → Firestore Database
  2. Click "Create database"
  3. Select "Start in test mode"
  4. Choose a location closest to your users
  5. Click "Enable"

Step 5: Configure Security Rules

In Firestore → Rules tab, replace with:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }

    match /gameStates/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }

    match /lessonProgress/{userId}/{document=**} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

Click "Publish" to save.

Step 6: Add Credentials to Your Project

Edit .env.local with your Firebase config:

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

Gemini API Setup

  1. Go to Google AI Studio
  2. Create an API key
  3. Add to .env.local: 
    NEXT_PUBLIC_GEMINI_API_KEY=your_gemini_api_key

Deployment

GitHub Pages

The project is configured for GitHub Pages deployment via GitHub Actions.

  1. Add GitHub Secrets

    Go to your repo → Settings → Secrets → Actions, and add:

    • NEXT_PUBLIC_FIREBASE_API_KEY
    • NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN
    • NEXT_PUBLIC_FIREBASE_PROJECT_ID
    • NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET
    • NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID
    • NEXT_PUBLIC_FIREBASE_APP_ID
    • NEXT_PUBLIC_GEMINI_API_KEY

  2. Enable GitHub Pages

    Go to Settings → Pages → Source → Select "GitHub Actions"

  3. Push to main branch

    The workflow will automatically build and deploy.

Manual Build

npm run build

The static site will be generated in the out/ directory.

Project Structure

src/
├── app/                    # Next.js App Router pages
│   ├── (auth)/            # Auth pages (login, register)
│   ├── dashboard/         # Learner dashboard pages
│   │   ├── achievements/  # Achievements page
│   │   ├── games/         # Games hub and individual games
│   │   ├── profile/       # User profile page
│   │   ├── progress/      # Progress tracking page
│   │   ├── quests/        # Daily quests page
│   │   ├── settings/      # Settings page
│   │   └── worlds/        # Learning worlds and lessons
│   ├── teacher/           # Teacher dashboard (classroom management)
│   └── parent/            # Parent dashboard (child progress)
├── components/
│   ├── ui/                # Base UI components
│   ├── phonics/           # Phoneme display components
│   ├── audio/             # Audio/speech components
│   ├── games/             # Game components
│   ├── lesson/            # Lesson phase components
│   ├── sentences/         # Intonation training components
│   ├── chatbot/           # Phoni the helper chatbot
│   └── gamification/      # XP, achievements, quests
├── stores/                # Zustand state stores
├── lib/
│   ├── firebase/          # Firebase configuration & services
│   ├── audio/             # Audio utilities
│   └── ai/                # AI/Gemini integration
├── types/                 # TypeScript type definitions
├── constants/             # Phonemes, lessons, worlds, sentences data
└── hooks/                 # Custom React hooks

Learning Worlds

World Lessons Focus Phonemes Covered
🔤 Letters Land 20 Individual sounds Short/long vowels, consonants
🏙️ Word City 25 Blending & digraphs L-blends, R-blends, S-blends, digraphs
📜 Rule Realm 20 Vowel patterns R-controlled vowels, diphthongs
🚂 Sentence Station 15 Fluency Sentence-level reading
👑 Story Kingdom 15 Comprehension Paragraph & story reading

Total: 95 lessons covering all 44 English phonemes

Lesson Flow

Each lesson follows a 4-phase pedagogical framework:

┌─────────────────────────────────────────────────────────────────────┐
│  1. LISTEN        2. PRACTICE       3. PLAY          4. ASSESS     │
│  ───────────      ────────────      ─────────        ──────────    │
│  • Hear phoneme   • Record voice    • Word games     • Quiz time   │
│  • See IPA        • AI feedback     • Match sounds   • Earn stars  │
│  • View tips      • Get score       • Score points   • Unlock XP   │
└─────────────────────────────────────────────────────────────────────┘
Phase Description
Listen Students hear the phoneme and example words via TTS, see phoneme cards with IPA and mouth tips
Practice Students speak words, AI analyzes pronunciation and provides personalized feedback
Play Interactive games reinforce learning - match words to sounds
Assess Quick quiz to demonstrate mastery, earn stars based on performance

Features

AI-Powered Pronunciation

  • Gemini AI Feedback: Intelligent analysis of student pronunciation
  • Real-time Speech Recognition: Web Speech API captures student voice
  • Contextual Tips: AI provides phoneme-specific improvement suggestions
  • Adaptive Encouragement: Feedback adjusts based on attempt number and score

Phonics System

  • 44 English phonemes with IPA notation
  • Color-coded by category (vowels, consonants, digraphs)
  • Animated mouth position guides
  • Audio pronunciation with Web Speech API
  • 95 structured lessons covering all sounds

Intonation Training (Sentence Station)

  • Visual Intonation Markers: ↗️ rising, ↘️ falling, ➡️ sustained
  • Karaoke-style Text: Word-by-word highlighting synced with TTS
  • Sentence Types: Statements, yes/no questions, wh-questions, exclamations
  • Stress Indicators: Shows which words to emphasize
  • AI Feedback: Evaluates pronunciation, fluency, and intonation patterns

Games

  • Phoneme Pop: Tap bubbles with the target sound
  • Word Builder: Drag letter tiles to build words
  • Sound Match: Memory matching with audio
  • Sound Race: Speed-based phoneme identification
  • Sentence Scramble: Arrange words in order
  • Karaoke Challenge: Follow-along reading

Gamification

  • XP earned for completing lessons and games
  • Level progression system
  • Achievement badges (18 achievements across 4 categories)
  • Daily quests with bonus XP rewards
  • Streak tracking

Dashboard Pages

  • Progress: Track overall completion, world progress, and phoneme mastery
  • Quests: View and complete daily challenges
  • Achievements: Browse unlocked and locked badges
  • Games: Practice any phoneme with standalone games
  • Profile: View stats, level, and account information
  • Settings: Customize audio, speech, display, and gameplay options

Interactive Help

  • Phoni the Owl 🦉: Cute chatbot helper available on every page
  • Click the owl in the bottom-right corner to ask questions
  • Get instant answers about lessons, games, XP, and app features
  • Smart keyword matching for helpful responses

Role-Based System

  • Learners: Access lessons, games, track XP and achievements
  • Teachers: Create classrooms, share join codes, monitor student progress
  • Parents: Link to child accounts, view progress reports

Scripts

Command Description
npm run dev Start development server
npm run build Build for production
npm run start Start production server
npm run lint Run ESLint

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License.

Acknowledgments

  • Phoneme data based on standard American English pronunciation
  • Built with assistance from Claude AI

About

Interactive phonics learning app for ages 9-15 with games, AI features, and gamification. Built with Next.js, Firebase, and Gemini AI.

alfredang.github.io/phonics-ai/

Topics

firebase nextjs phonics kids-learn tailwindcss firestore-database github-actions

Resources

Readme
Activity

Stars

7 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages