Citizen Quiz

A conversational AI application designed to help users practice for the US Naturalization Test. The app simulates a verbal interview experience using AI-generated questions and feedback.

Features

• Conversational Interface: Uses OpenAI's GPT-4o to act as a practice examiner.
• Voice Interaction: Includes Text-to-Speech (TTS) for asking questions and Speech-to-Text (STT) for capturing user answers.
• Real-time Feedback: Provides immediate correction and explanation for answers.
• Audio Visualization: Visual feedback during listening and speaking phases.

Getting Started

Prerequisites

• Node.js (v18+ recommended)
• OpenAI API Key

Installation

1. Clone the repository:

   git clone https://github.com/jGiltinan/Citizen_Quiz.git
   cd Citizen_Quiz

2. Install dependencies:

   npm install

3. Set up environment variables: Create a .env file in the root directory and add your OpenAI API key and Vector Store ID:

   OPENAI_API_KEY=your_api_key_here
   OPENAI_VECTOR_STORE_ID=your_vector_store_id_here

   Note: This app requires an OpenAI Vector Store containing the US Naturalization Test questions (PDF/Text).

Creating the Vector Store

To make this app work, you need to provide it with the knowledge base (the test questions).

1. Prepare your document: Download the 100 Civics Questions (PDF) or create a text file with the questions.

2. Go to OpenAI Platform: Navigate to the Vector Stores dashboard.

3. Create New Store: Click "+ Create", name it (e.g., "Citizen Quiz"), and upload your document.

4. Get the ID: Copy the ID (starts with vs_...) and paste it into your .env file as OPENAI_VECTOR_STORE_ID.

5. Run the development server:

   npm run dev

6. Open http://localhost:3000 with your browser.

iOS & Audio Support

Special attention has been given to support iOS devices (iPhone/iPad), which have strict policies regarding audio autoplay and microphone usage.

• Audio Unlock: The app plays a silent sound immediately upon "Start Quiz" to unlock the audio context for Safari.
• Robust Recording: The app acquires a fresh microphone stream for every question to maintain stability on iOS.
• Fallback Mode: If audio playback fails or the network is slow, the app includes a fallback to the device's system voice (SpeechSynthesis) to ensure the quiz can continue.

Warning

Known Issue (Non-iOS Devices): The "fresh stream" logic implemented for iOS stability may cause regressions or instability on some Android or Desktop browsers. If you experience microphone issues on non-Apple devices, consider refreshing the page.

Tech Stack

• Framework: Next.js
• AI/LLM: OpenAI GPT-4o (Assistant API/Chat Completions)
• Audio: OpenAI TTS & Whisper (for transcription)
• Styling: Tailwind CSS, Framer Motion

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.