README.md

---
title: QuizFlash - AI-Powered Quiz Generation
emoji: 🎓
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
app_port: 3000
---

# QuizFlash 🚀

An intelligent quiz generation platform powered by AI that creates customizable educational questions from any source material.

## Features

- **Multiple Question Types**: Support for multiple choice, cloze (fill-in-the-blank), grammar check, reading comprehension, and essay questions
- **AI-Powered Generation**: Uses OpenAI GPT-4 to generate high-quality, educational questions
- **Configurable Parameters**: Each question type has customizable difficulty levels and specific parameters
- **Source Material Support**: Generate questions based on your own text content
- **Real-time Question Bank**: Build and manage a collection of generated questions
- **Modern UI**: Clean, responsive interface built with Next.js and Tailwind CSS

## Getting Started

First, run the development server:

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.

## System Architecture

```mermaid
graph TD
    A["🔧 Question Config<br/>(questionConfig.ts)"] --> B["📋 Parameter Form<br/>(QuestionParameterForm)"]
    B --> C["🎛️ Parameter Input<br/>(ParameterInput)"]
    C --> D["👤 User Input<br/>(UI Interaction)"]
    D --> E["📊 Parameters Object<br/>(QuestionParameters)"]
    
    E --> F["🎯 Question Type<br/>Selection"]
    F --> G["📝 Source Material<br/>(Optional)"]
    
    E --> H["🚀 Generate Question<br/>(API Call)"]
    G --> H
    
    H --> I["🤖 AI Generation<br/>(OpenAI API)"]
    
    I --> J["📄 Prompt Templates<br/>(prompt-management.ts)"]
    J --> K["🔄 Template Rendering<br/>(renderTemplate)"]
    K --> L["📤 Final Prompt<br/>(to AI Model)"]
    
    L --> M["🧠 AI Processing<br/>(GPT-4 Mini)"]
    M --> N["📋 Zod Schema<br/>Validation"]
    N --> O["✅ Structured Response<br/>(JSON Object)"]
    
    O --> P["💾 Question Bank<br/>(State Management)"]
    P --> Q["🎴 Question Card<br/>(UI Component)"]
    
    Q --> R["👁️ User Display<br/>(Question Bank UI)"]
    
    subgraph "Configuration Layer"
        A
        B
        C
    end
    
    subgraph "User Interaction Layer"
        D
        E
        F
        G
    end
    
    subgraph "API Processing Layer"
        H
        I
        J
        K
        L
    end
    
    subgraph "AI Generation Layer"
        M
        N
        O
    end
    
    subgraph "Display Layer"
        P
        Q
        R
    end
    
    style A fill:#e1f5fe
    style J fill:#fff3e0
    style Q fill:#f3e5f5
    style M fill:#e8f5e8
```

### Flow Description

#### 1. Configuration Layer
- **Question Config**: Abstract configuration system that defines parameter schemas for each question type
- **Parameter Form**: Dynamically renders form fields based on the configuration
- **Parameter Input**: Reusable input components (select, range, input, checkbox)

#### 2. User Interaction Layer
- **User Input**: Users interact with dynamically generated parameter forms
- **Parameters Object**: Collects user preferences (difficulty, number of options, etc.)
- **Question Type Selection**: Users choose from available question types
- **Source Material**: Optional text input to provide context for questions

#### 3. API Processing Layer
- **Generate Question**: API endpoint processes the generation request
- **Prompt Templates**: Pre-defined, configurable templates for each question type
- **Template Rendering**: Dynamic substitution of user parameters into prompt templates
- **Final Prompt**: Complete, contextualized prompt ready for AI processing

#### 4. AI Generation Layer
- **AI Processing**: OpenAI GPT-4 Mini generates questions based on the prompt
- **Zod Schema Validation**: Ensures AI responses match expected structure
- **Structured Response**: Clean, validated JSON object containing question data

#### 5. Display Layer
- **Question Bank**: State management for storing and organizing generated questions
- **Question Card**: UI components for rendering individual questions
- **User Display**: Final question bank interface with selection and management features

### Key Architecture Benefits

- **🔧 Configurable**: Adding new question types requires only configuration changes
- **♻️ Reusable**: Components work across all question types
- **🛡️ Type-Safe**: Full TypeScript support throughout the entire flow
- **📦 Modular**: Clean separation of concerns between layers
- **🚀 Scalable**: Easy to extend with new features and question types

## Tech Stack

- **Frontend**: Next.js 14, React, TypeScript, Tailwind CSS
- **AI Integration**: OpenAI GPT-4 Mini, Vercel AI SDK
- **Validation**: Zod schema validation
- **Styling**: Tailwind CSS with dark mode support
- **State Management**: React hooks and context

## Project Structure

```
src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── chat/         # Chat functionality
│   │   ├── generate-question/ # Single question generation
│   │   └── generate-quiz/ # Multiple question generation
│   └── page.tsx          # Main application page
├── components/            # React components
│   ├── QuestionParameterForm.tsx  # Dynamic parameter form
│   └── ParameterInput.tsx         # Reusable input components
├── types/                 # TypeScript type definitions
│   ├── quiz.ts           # Core quiz types
│   └── questionConfig.ts # Configuration types and schemas
└── prompts/              # AI prompt templates
    └── prompt-management.ts # Question generation prompts
```

## Adding New Question Types

Thanks to the abstract configuration system, adding new question types is incredibly simple:

1. Add configuration to `src/types/questionConfig.ts`:
```typescript
'your-new-type': {
  id: 'your-new-type',
  parameters: [
    {
      key: 'difficulty',
      label: 'Difficulty Level',
      type: 'select',
      defaultValue: 'intermediate',
      options: [
        { value: 'beginner', label: 'Beginner' },
        { value: 'intermediate', label: 'Intermediate' },
        { value: 'advanced', label: 'Advanced' },
      ],
    },
    // Add more parameters as needed
  ],
}
```

2. That's it! No component modifications required. The UI will automatically render the appropriate form fields.

## Learn More

To learn more about the technologies used:

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API
- [Vercel AI SDK](https://sdk.vercel.ai/docs) - AI integration toolkit
- [OpenAI API](https://platform.openai.com/docs) - AI model documentation
- [Tailwind CSS](https://tailwindcss.com/docs) - utility-first CSS framework

## Deploy on Vercel

The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.

Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.