---

📖 Overview

A full-stack web application for IELTS speaking practice, built with FastAPI (backend) and Next.js with Tailwind CSS (frontend). Features AI-powered speech transcription using Whisper and text-to-speech for question audio playback.

✨ Features

• 🏠 Homepage Dashboard - Progress tracking, streaks, and GitHub-style activity calendar
• 📝 Practice by Question - Practice questions from Part 1, 2, and 3 with instant feedback
• 🎯 Mock Tests - Take full or partial mock tests simulating real IELTS exam conditions
• 📊 Progress Tracking - Daily progress, streaks, and part-wise progress analytics
• 👤 User Management - Secure authentication with Google OAuth support
• 📈 Activity Calendar - Visual GitHub-style contribution graph showing practice history
• 🎤 AI-Powered Transcription - Automatic speech-to-text using Whisper AI
• 🔊 Text-to-Speech - Question audio playback using Puter.js TTS
• 📱 Responsive Design - Beautiful UI built with Tailwind CSS
• 🔄 Real-time Updates - Live progress tracking and streak management

📋 Table of Contents

• Quick Start
• Project Structure
• Features
• Tech Stack
• API Endpoints
• Database Schema
• Development
• Deployment
• Google OAuth Setup
• License

📁 Project Structure

english_speaking_test/
├── backend/          # FastAPI backend
│   ├── app/
│   │   ├── routers/  # API routes
│   │   ├── models.py # Database models
│   │   ├── schemas.py # Pydantic schemas
│   │   └── main.py   # FastAPI app
│   ├── database/
│   │   └── schema.sql # Database schema
│   └── requirements.txt
├── frontend/         # Next.js frontend
│   ├── app/          # Next.js app directory
│   ├── components/   # React components
│   ├── lib/          # Utilities and API client
│   └── package.json
└── README.md

🚀 Quick Start

For detailed setup instructions, see Quick Start Guide.

Backend Setup

1. Navigate to backend directory:

cd backend

2. Create virtual environment and install dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Set up PostgreSQL database:

# Create database
createdb ielts_speaking

# Run schema
psql ielts_speaking < database/schema.sql

4. Create .env file:

cp .env.example .env
# Edit .env with your database credentials:
# DATABASE_URL=postgresql://user:password@localhost:5432/ielts_speaking
# SECRET_KEY=your-secret-key-change-in-production
# GOOGLE_CLIENT_ID=your-google-client-id  # For Google OAuth

5. Run the server:

uvicorn app.main:app --reload --port 8000

Backend will be available at http://localhost:8000 API docs at http://localhost:8000/docs

Frontend Setup

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install
# or
yarn install

3. Create .env.local file:

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-google-client-id  # For Google OAuth

4. Run the development server:

npm run dev
# or
yarn dev

Frontend will be available at http://localhost:3000

🗄️ Database Schema

The application uses PostgreSQL with the following main tables:

• users - User accounts
• questions - Practice questions
• user_questions - Custom questions added by users
• practice_sessions - Practice session records
• mock_tests - Mock test records
• daily_progress - Daily practice progress
• streaks - User streak tracking
• activity_calendar - Activity calendar data
• part_progress - Progress by IELTS part (1, 2, 3)

See backend/database/schema.sql for the complete schema.

🔌 API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login
• POST /api/auth/google - Login/Register with Google OAuth
• GET /api/auth/me - Get current user

Questions

• GET /api/questions/ - Get questions (with optional part and topic filters)
• GET /api/questions/topics - Get all topics
• GET /api/questions/user-questions - Get user's custom questions
• POST /api/questions/user-questions - Create custom question
• DELETE /api/questions/user-questions/{id} - Delete custom question

Practice

• POST /api/practice/ - Create practice session
• GET /api/practice/ - Get practice sessions

Mock Tests

• POST /api/mock-test/ - Create mock test
• GET /api/mock-test/ - Get mock tests
• GET /api/mock-test/{id} - Get specific mock test

Progress

• GET /api/progress/daily - Get daily progress
• GET /api/progress/streak - Get streak info
• GET /api/progress/activity-calendar - Get activity calendar
• GET /api/progress/part-progress - Get part-wise progress

🛠️ Tech Stack

Backend

• FastAPI - Modern Python web framework
• SQLAlchemy - ORM
• PostgreSQL - Database
• Pydantic - Data validation
• JWT - Authentication

Frontend

• Next.js 14 - React framework
• TypeScript - Type safety
• Tailwind CSS - Styling
• Axios - HTTP client
• Zustand - State management

💻 Development

Adding Questions

You can add questions to the database by inserting into the questions table:

INSERT INTO questions (part, topic, question_text) VALUES
(1, 'Doing something well', 'Do you have an experience when you did something well?'),
(1, 'Rules', 'Are there any rules for students at your school?');

Environment Variables

For detailed environment variable setup, see Environment Setup Guide.

Backend (.env):

• DATABASE_URL - PostgreSQL connection string
• SECRET_KEY - Secret key for JWT tokens
• GOOGLE_CLIENT_ID - Google OAuth Client ID (get from Google Cloud Console)

Frontend (.env.local):

• NEXT_PUBLIC_API_URL - Backend API URL
• NEXT_PUBLIC_GOOGLE_CLIENT_ID - Google OAuth Client ID (same as backend)

🚀 Deployment

To deploy your application to production, see the comprehensive deployment guides:

• Quick Start Deployment - Fast deployment options (Vercel + Railway)
• Full Deployment Guide - Detailed instructions for multiple platforms:
  • Vercel + Railway/Render (Recommended)
  • Docker Compose
  • Traditional VPS (Ubuntu/Debian)
  • AWS/GCP/Azure

Quick Deploy

Easiest option: Deploy frontend to Vercel and backend to Railway. See DEPLOY_QUICKSTART.md for step-by-step instructions.

🔐 Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable Google+ API
4. Go to "Credentials" → "Create Credentials" → "OAuth client ID"
5. Configure OAuth consent screen
6. Create OAuth 2.0 Client ID for Web application
7. Add authorized JavaScript origins: http://localhost:3000 (for development)
8. Add authorized redirect URIs: http://localhost:3000 (for development)
9. Copy the Client ID and add it to both backend .env and frontend .env.local files

Note: For production, update the authorized origins and redirect URIs to your production domain.

📄 License

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

---