Update readme

README.md

@@ -1,4 +1,15 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# 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
 
@@ -18,16 +29,175 @@ Open [http://localhost:3000](http://localhost:3000) with your browser to see the
 
 You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+## System Architecture
 
-## Learn More
+```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/>(quiz-generation.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
 
-To learn more about Next.js, take a look at the following resources:
+## 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
+    └── quiz-generation.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
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+To learn more about the technologies used:
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+- [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
 

src/components/ParameterInput.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+import { ParameterConfig } from '@/types/questionConfig';
+
+interface ParameterInputProps {
+  config: ParameterConfig;
+  value: any;
+  onChange: (value: any) => void;
+}
+
+export default function ParameterInput({ config, value, onChange }: ParameterInputProps) {
+  const { key, label, type, options, min, max, step, placeholder, helpText } = config;
+  
+  const currentValue = value ?? config.defaultValue;
+
+  const baseInputClasses = "w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500";
+
+  switch (type) {
+    case 'select':
+      return (
+        <div>
+          <label className="block text-sm font-medium mb-2">{label}</label>
+          <select 
+            value={currentValue}
+            onChange={(e) => {
+              const val = options?.find(opt => opt.value.toString() === e.target.value)?.value;
+              onChange(val);
+            }}
+            className={baseInputClasses}
+          >
+            {options?.map((option) => (
+              <option key={option.value.toString()} value={option.value.toString()}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+        </div>
+      );
+
+    case 'range':
+      return (
+        <div>
+          <label className="block text-sm font-medium mb-2">{label}</label>
+          <input 
+            type="range" 
+            min={min} 
+            max={max} 
+            step={step}
+            value={currentValue}
+            onChange={(e) => onChange(parseInt(e.target.value))}
+            className="w-full"
+          />
+          <div className="text-center text-sm text-gray-600">
+            {currentValue} {helpText}
+          </div>
+        </div>
+      );
+
+    case 'input':
+      return (
+        <div>
+          <label className="block text-sm font-medium mb-2">{label}</label>
+          <input 
+            type="text"
+            value={currentValue || ''}
+            placeholder={placeholder}
+            onChange={(e) => onChange(e.target.value)}
+            className={baseInputClasses}
+          />
+          {helpText && (
+            <div className="text-xs text-gray-500 mt-1">{helpText}</div>
+          )}
+        </div>
+      );
+
+    case 'checkbox':
+      return (
+        <div className="flex items-center">
+          <input 
+            type="checkbox"
+            id={key}
+            checked={currentValue || false}
+            onChange={(e) => onChange(e.target.checked)}
+            className="mr-2"
+          />
+          <label htmlFor={key} className="text-sm font-medium">{label}</label>
+          {helpText && (
+            <div className="text-xs text-gray-500 ml-2">{helpText}</div>
+          )}
+        </div>
+      );
+
+    default:
+      return null;
+  }
+}

src/components/QuestionParameterForm.tsx

@@ -1,6 +1,8 @@
 'use client';
 
 import { QuestionType, QuestionParameters } from '@/types/quiz';
+import { questionTypeConfigs, defaultQuestionTypeConfig } from '@/types/questionConfig';
+import ParameterInput from './ParameterInput';
 
 interface QuestionParameterFormProps {
   questionType: QuestionType;
@@ -17,194 +19,19 @@ export default function QuestionParameterForm({
     onParametersChange({ ...parameters, [key]: value });
   };
 
-  switch (questionType.id) {
-    case 'multiple-choice':
-      return (
-        <div className="space-y-4">
-          <div>
-            <label className="block text-sm font-medium mb-2">Difficulty Level</label>
-            <select 
-              value={parameters.difficulty || 'intermediate'}
-              onChange={(e) => updateParameter('difficulty', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="beginner">Beginner</option>
-              <option value="intermediate">Intermediate</option>
-              <option value="advanced">Advanced</option>
-            </select>
-          </div>
-          <div>
-            <label className="block text-sm font-medium mb-2">Number of Options</label>
-            <select 
-              value={parameters.numOptions || 4}
-              onChange={(e) => updateParameter('numOptions', parseInt(e.target.value))}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value={3}>3 Options</option>
-              <option value={4}>4 Options</option>
-              <option value={5}>5 Options</option>
-            </select>
-          </div>
-        </div>
-      );
-    
-    case 'cloze':
-      return (
-        <div className="space-y-4">
-          <div>
-            <label className="block text-sm font-medium mb-2">Target Part of Speech</label>
-            <select 
-              value={parameters.partOfSpeech || 'any'}
-              onChange={(e) => updateParameter('partOfSpeech', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="any">Any</option>
-              <option value="noun">Nouns</option>
-              <option value="verb">Verbs</option>
-              <option value="adjective">Adjectives</option>
-              <option value="adverb">Adverbs</option>
-            </select>
-          </div>
-          <div>
-            <label className="block text-sm font-medium mb-2">Number of Blanks</label>
-            <input 
-              type="range" 
-              min="1" 
-              max="5" 
-              value={parameters.numBlanks || 1}
-              onChange={(e) => updateParameter('numBlanks', parseInt(e.target.value))}
-              className="w-full"
-            />
-            <div className="text-center text-sm text-gray-600">{parameters.numBlanks || 1} blank(s)</div>
-          </div>
-        </div>
-      );
-    
-    case 'grammar':
-      return (
-        <div className="space-y-4">
-          <div>
-            <label className="block text-sm font-medium mb-2">Difficulty Level</label>
-            <select 
-              value={parameters.difficulty || 'intermediate'}
-              onChange={(e) => updateParameter('difficulty', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="beginner">Beginner</option>
-              <option value="intermediate">Intermediate</option>
-              <option value="advanced">Advanced</option>
-            </select>
-          </div>
-          <div>
-            <label className="block text-sm font-medium mb-2">Grammar Focus</label>
-            <select 
-              value={parameters.grammarFocus || 'any'}
-              onChange={(e) => updateParameter('grammarFocus', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="any">Any Grammar Rule</option>
-              <option value="verb-tenses">Verb Tenses</option>
-              <option value="subject-verb">Subject-Verb Agreement</option>
-              <option value="punctuation">Punctuation</option>
-              <option value="sentence-structure">Sentence Structure</option>
-            </select>
-          </div>
-        </div>
-      );
+  // Get configuration for this question type, fallback to default
+  const config = questionTypeConfigs[questionType.id] || defaultQuestionTypeConfig;
 
-    case 'reading-comp':
-      return (
-        <div className="space-y-4">
-          <div>
-            <label className="block text-sm font-medium mb-2">Difficulty Level</label>
-            <select 
-              value={parameters.difficulty || 'intermediate'}
-              onChange={(e) => updateParameter('difficulty', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="beginner">Beginner</option>
-              <option value="intermediate">Intermediate</option>
-              <option value="advanced">Advanced</option>
-            </select>
-          </div>
-          <div>
-            <label className="block text-sm font-medium mb-2">Question Focus</label>
-            <select 
-              value={parameters.focus || 'comprehension'}
-              onChange={(e) => updateParameter('focus', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="comprehension">General Comprehension</option>
-              <option value="inference">Making Inferences</option>
-              <option value="main-idea">Main Ideas</option>
-              <option value="details">Supporting Details</option>
-              <option value="vocabulary">Vocabulary in Context</option>
-            </select>
-          </div>
-        </div>
-      );
-
-    case 'essay':
-      return (
-        <div className="space-y-4">
-          <div>
-            <label className="block text-sm font-medium mb-2">Difficulty Level</label>
-            <select 
-              value={parameters.difficulty || 'intermediate'}
-              onChange={(e) => updateParameter('difficulty', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="beginner">Beginner</option>
-              <option value="intermediate">Intermediate</option>
-              <option value="advanced">Advanced</option>
-            </select>
-          </div>
-          <div>
-            <label className="block text-sm font-medium mb-2">Essay Type</label>
-            <select 
-              value={parameters.essayType || 'argumentative'}
-              onChange={(e) => updateParameter('essayType', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="argumentative">Argumentative</option>
-              <option value="descriptive">Descriptive</option>
-              <option value="narrative">Narrative</option>
-              <option value="expository">Expository</option>
-              <option value="compare-contrast">Compare & Contrast</option>
-            </select>
-          </div>
-          <div>
-            <label className="block text-sm font-medium mb-2">Word Count Range</label>
-            <select 
-              value={parameters.wordCount || '300-500'}
-              onChange={(e) => updateParameter('wordCount', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="150-250">150-250 words</option>
-              <option value="300-500">300-500 words</option>
-              <option value="500-750">500-750 words</option>
-              <option value="750-1000">750-1000 words</option>
-            </select>
-          </div>
-        </div>
-      );
-    
-    default:
-      return (
-        <div className="space-y-4">
-          <div>
-            <label className="block text-sm font-medium mb-2">Difficulty Level</label>
-            <select 
-              value={parameters.difficulty || 'intermediate'}
-              onChange={(e) => updateParameter('difficulty', e.target.value)}
-              className="w-full p-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
-            >
-              <option value="beginner">Beginner</option>
-              <option value="intermediate">Intermediate</option>
-              <option value="advanced">Advanced</option>
-            </select>
-          </div>
-        </div>
-      );
-  }
+  return (
+    <div className="space-y-4">
+      {config.parameters.map((paramConfig) => (
+        <ParameterInput
+          key={paramConfig.key}
+          config={paramConfig}
+          value={parameters[paramConfig.key]}
+          onChange={(value) => updateParameter(paramConfig.key, value)}
+        />
+      ))}
+    </div>
+  );
 }

src/types/questionConfig.ts

@@ -0,0 +1,204 @@
+export type ParameterType = 'select' | 'range' | 'input' | 'checkbox';
+
+export interface ParameterOption {
+  value: string | number;
+  label: string;
+}
+
+export interface ParameterConfig {
+  key: string;
+  label: string;
+  type: ParameterType;
+  defaultValue?: any;
+  options?: ParameterOption[];
+  min?: number;
+  max?: number;
+  step?: number;
+  placeholder?: string;
+  helpText?: string;
+}
+
+export interface QuestionTypeConfig {
+  id: string;
+  parameters: ParameterConfig[];
+}
+
+// Configuration for each question type
+export const questionTypeConfigs: Record<string, QuestionTypeConfig> = {
+  'multiple-choice': {
+    id: 'multiple-choice',
+    parameters: [
+      {
+        key: 'difficulty',
+        label: 'Difficulty Level',
+        type: 'select',
+        defaultValue: 'intermediate',
+        options: [
+          { value: 'beginner', label: 'Beginner' },
+          { value: 'intermediate', label: 'Intermediate' },
+          { value: 'advanced', label: 'Advanced' },
+        ],
+      },
+      {
+        key: 'numOptions',
+        label: 'Number of Options',
+        type: 'select',
+        defaultValue: 4,
+        options: [
+          { value: 3, label: '3 Options' },
+          { value: 4, label: '4 Options' },
+          { value: 5, label: '5 Options' },
+        ],
+      },
+    ],
+  },
+  
+  'cloze': {
+    id: 'cloze',
+    parameters: [
+      {
+        key: 'partOfSpeech',
+        label: 'Target Part of Speech',
+        type: 'select',
+        defaultValue: 'any',
+        options: [
+          { value: 'any', label: 'Any' },
+          { value: 'noun', label: 'Nouns' },
+          { value: 'verb', label: 'Verbs' },
+          { value: 'adjective', label: 'Adjectives' },
+          { value: 'adverb', label: 'Adverbs' },
+        ],
+      },
+      {
+        key: 'numBlanks',
+        label: 'Number of Blanks',
+        type: 'range',
+        defaultValue: 1,
+        min: 1,
+        max: 5,
+        step: 1,
+        helpText: 'blank(s)',
+      },
+    ],
+  },
+  
+  'grammar': {
+    id: 'grammar',
+    parameters: [
+      {
+        key: 'difficulty',
+        label: 'Difficulty Level',
+        type: 'select',
+        defaultValue: 'intermediate',
+        options: [
+          { value: 'beginner', label: 'Beginner' },
+          { value: 'intermediate', label: 'Intermediate' },
+          { value: 'advanced', label: 'Advanced' },
+        ],
+      },
+      {
+        key: 'grammarFocus',
+        label: 'Grammar Focus',
+        type: 'select',
+        defaultValue: 'any',
+        options: [
+          { value: 'any', label: 'Any Grammar Rule' },
+          { value: 'verb-tenses', label: 'Verb Tenses' },
+          { value: 'subject-verb', label: 'Subject-Verb Agreement' },
+          { value: 'punctuation', label: 'Punctuation' },
+          { value: 'sentence-structure', label: 'Sentence Structure' },
+        ],
+      },
+    ],
+  },
+  
+  'reading-comp': {
+    id: 'reading-comp',
+    parameters: [
+      {
+        key: 'difficulty',
+        label: 'Difficulty Level',
+        type: 'select',
+        defaultValue: 'intermediate',
+        options: [
+          { value: 'beginner', label: 'Beginner' },
+          { value: 'intermediate', label: 'Intermediate' },
+          { value: 'advanced', label: 'Advanced' },
+        ],
+      },
+      {
+        key: 'focus',
+        label: 'Question Focus',
+        type: 'select',
+        defaultValue: 'comprehension',
+        options: [
+          { value: 'comprehension', label: 'General Comprehension' },
+          { value: 'inference', label: 'Making Inferences' },
+          { value: 'main-idea', label: 'Main Ideas' },
+          { value: 'details', label: 'Supporting Details' },
+          { value: 'vocabulary', label: 'Vocabulary in Context' },
+        ],
+      },
+    ],
+  },
+  
+  'essay': {
+    id: 'essay',
+    parameters: [
+      {
+        key: 'difficulty',
+        label: 'Difficulty Level',
+        type: 'select',
+        defaultValue: 'intermediate',
+        options: [
+          { value: 'beginner', label: 'Beginner' },
+          { value: 'intermediate', label: 'Intermediate' },
+          { value: 'advanced', label: 'Advanced' },
+        ],
+      },
+      {
+        key: 'essayType',
+        label: 'Essay Type',
+        type: 'select',
+        defaultValue: 'argumentative',
+        options: [
+          { value: 'argumentative', label: 'Argumentative' },
+          { value: 'descriptive', label: 'Descriptive' },
+          { value: 'narrative', label: 'Narrative' },
+          { value: 'expository', label: 'Expository' },
+          { value: 'compare-contrast', label: 'Compare & Contrast' },
+        ],
+      },
+      {
+        key: 'wordCount',
+        label: 'Word Count Range',
+        type: 'select',
+        defaultValue: '300-500',
+        options: [
+          { value: '150-250', label: '150-250 words' },
+          { value: '300-500', label: '300-500 words' },
+          { value: '500-750', label: '500-750 words' },
+          { value: '750-1000', label: '750-1000 words' },
+        ],
+      },
+    ],
+  },
+};
+
+// Default configuration for unknown question types
+export const defaultQuestionTypeConfig: QuestionTypeConfig = {
+  id: 'default',
+  parameters: [
+    {
+      key: 'difficulty',
+      label: 'Difficulty Level',
+      type: 'select',
+      defaultValue: 'intermediate',
+      options: [
+        { value: 'beginner', label: 'Beginner' },
+        { value: 'intermediate', label: 'Intermediate' },
+        { value: 'advanced', label: 'Advanced' },
+      ],
+    },
+  ],
+};