🎯 Memocards - AI-Powered Quiz Generator

Interactive quiz generation interface with AI-powered content transformation

A comprehensive web application that transforms any text content into interactive, educational quizzes using AI technology. Built with modern web technologies and designed for seamless user experience.

✨ Features

🤖 AI-Powered Quiz Generation

Convert any text content (50-15,000 characters) into engaging multiple-choice quizzes
Supports 25+ languages with auto-detection
Three difficulty levels: Easy, Medium, Hard
Intelligent question generation with plausible distractors

🎮 Interactive Quiz Experience

Real-time Answer Validation: Immediate feedback on answer selection
Smart Scoring System: First-attempt scoring with retry capability
Visual Feedback: Green highlights for correct answers, justifications displayed
Free Navigation: Move between questions freely without restrictions
Progress Tracking: Current question indicator and completion status

📊 Comprehensive Results

Dynamic Score Display: Visual score circle with percentage
Performance Analytics: First-attempt score vs. total attempts
Adaptive Messaging: Personalized congratulations based on performance
Color-coded Results: Visual feedback reflecting achievement level
Time Tracking: Quiz completion time display

🎨 Modern UI/UX

Responsive Design: Works perfectly on desktop, tablet, and mobile
Tailwind CSS: Modern, clean, and accessible interface
Smooth Animations: Loading states and transition effects
Intuitive Navigation: Clear user flow from input to results

⚙️ Advanced Configuration

Flexible Question Count: 1-25 questions per quiz
Multi-language Support: Auto-detect or manually select language
Difficulty Scaling: Adaptive question complexity
Real-time Validation: Input validation with helpful error messages

🚀 Quick Start

Prerequisites

n8n instance (local or cloud)
OpenRouter API key for AI generation
Modern web browser with JavaScript enabled

1. Setup n8n Workflow

Import Workflow: Import MemCards.json into your n8n instance
Configure AI Model: Add your OpenRouter API credentials to the "🚀 OpenRouter AI Model" node
Activate Workflow: Enable the workflow in n8n
Copy Webhook URL: Note the webhook URL (format: https://your-n8n.com/webhook/quiz-generator)

2. Configure Frontend

Update API URL: Edit assets/script.js, line 8:

this.apiUrl = 'https://your-n8n-instance.com/webhook/quiz-generator';

For Local Testing: Use localhost URL:

this.apiUrl = 'http://localhost:5678/webhook/quiz-generator';

3. Launch Application

Open index.html in a web browser
Enter Content: Paste your text content (minimum 50 characters)
Configure Quiz: Set title, question count, difficulty, and language
Generate: Click "Generate Quiz" and wait for AI processing
Take Quiz: Answer questions with immediate feedback
View Results: See your score, performance analytics, and personalized message

📁 Project Structure

Memocards/
├── 📄 index.html                    # Landing page with form inputs
├── 📁 assets/
│   ├── 🔧 script.js                # Main application logic (990+ lines)
│   ├── 🎨 style.css                # Custom styles (extends Tailwind)
│   ├── 📁 html/
│   │   ├── 📄 index2.html          # Interactive quiz interface
│   │   └── 📄 index3.html          # Results and analytics page
│   └── 📁 images/
│       ├── 🖼️ Group.svg            # Logo
│       └── 🖼️ mynaui_arrow-up-solid.svg # UI icons
├── 🤖 MemCards.json                # n8n AI workflow definition
└── 📚 README.md                    # Project documentation

Core Components

🖥️ Frontend (Client-Side)

Landing Page (index.html): Form inputs, validation, configuration
Quiz Interface (index2.html): Question display, answer selection, navigation
Results Page (index3.html): Score display, analytics, performance feedback
Main Logic (script.js): Quiz management, API integration, state handling

🤖 Backend (n8n Workflow)

Workflow Definition (MemCards.json): Complete n8n workflow for import
AI Processing: Generates questions using OpenRouter/OpenAI
Response Formatting: Structures data for frontend consumption

🔄 Application Flow

1. 📝 Content Input & Configuration

User Input → Validation → Configuration
├── Text content (50-15,000 chars)
├── Quiz title (optional)
├── Question count (1-25)
├── Difficulty level (Easy/Medium/Hard)
└── Language selection (Auto-detect + 6 languages)

2. 🤖 AI-Powered Quiz Generation

Frontend → n8n Webhook → AI Processing → Structured Response
├── POST request with user data
├── Input validation & sanitization
├── AI prompt engineering
├── Response parsing & validation
└── Fallback question generation

3. 🎮 Interactive Quiz Experience

Question Display → Answer Selection → Immediate Feedback
├── Real-time answer validation
├── Visual feedback (green/red highlighting)
├── Justification display for correct answers
├── First-attempt scoring system
└── Free navigation between questions

4. 📊 Results & Analytics

Score Calculation → Performance Analysis → Visual Display
├── First-attempt vs. total score
├── Percentage calculation
├── Time tracking
├── Personalized messaging
└── Color-coded performance indicators

🔌 API Integration

Request Format

POST /webhook/quiz-generator
Content-Type: application/json

{
  "text_content": "Your educational content here...",
  "question_count": 10,
  "difficulty": "Medium",
  "language": "Auto-detect from text"
}

Response Format

{
  "success": true,
  "quiz": [
    {
      "id": "q1",
      "question": "What is the main concept discussed?",
      "answers": [
        "The primary topic",
        "A secondary theme", 
        "Supporting details",
        "Background information"
      ],
      "correctAnswer": "A",
      "justification": "This represents the main focus of the content.",
      "difficulty": "Medium",
      "topic": "Content Analysis",
      "generated_at": "2025-09-28T12:00:00.000Z"
    }
  ],
  "metadata": {
    "request_id": "quiz_1727520000000",
    "total_questions": 10,
    "generated_at": "2025-09-28T12:00:00.000Z",
    "language": "English",
    "difficulty": "Medium",
    "word_count": 250
  }
}

⚙️ Configuration & Customization

🎛️ Quiz Settings

// In config.js or script.js
const QUIZ_CONFIG = {
  questionCount: [5, 10, 15, 20, 25],    // Available options
  difficulties: ['Easy', 'Medium', 'Hard'], // Difficulty levels
  languages: [                           // Supported languages
    'Auto-detect', 'English', 'French', 
    'Spanish', 'German', 'Italian', 'Portuguese'
  ],
  validation: {
    minTextLength: 50,      // Minimum content length
    maxTextLength: 15000,   // Maximum content length
    minQuestions: 1,        // Minimum questions
    maxQuestions: 25        // Maximum questions
  }
}

🎨 UI Customization

Colors: Modify Tailwind classes in HTML files
Layout: Adjust container sizes and spacing
Typography: Change font sizes and styles
Animations: Customize transition effects

📊 Scoring System

// Customizable scoring logic
const SCORING_CONFIG = {
  firstAttemptWeight: 1.0,    // Full points for first attempt
  retryPenalty: 0.0,          // No penalty for retries
  passingGrade: 60,           // 60% to pass
  excellentGrade: 90          // 90% for excellent
}

🐛 Troubleshooting

Common Issues & Solutions

Issue	Symptoms	Solution
API Connection Failed	"Failed to generate quiz" error	• Check n8n webhook URL • Verify workflow is active • Check CORS settings
Demo Quiz Always Shows	Same questions every time	• Configure correct API endpoint • Check n8n credentials • Verify network connectivity
Navigation Issues	Buttons not working	• Check file paths in HTML • Ensure script.js is loaded • Check browser console
Questions Not Displaying	Blank quiz interface	• Check quiz data format • Verify localStorage data • Check JavaScript errors
Scoring Issues	Incorrect score calculation	• Check answer format (A,B,C,D) • Verify first attempt tracking • Review score calculation logic

🔍 Debug Mode

Enable detailed logging by adding to browser console:

localStorage.setItem('memocards_debug', 'true');

📋 Health Check

Frontend: Open index.html → Check form inputs
API: Test webhook URL directly with POST request
n8n: Check workflow execution logs
Data Flow: Monitor browser network tab

🚨 Emergency Reset

Clear all stored data:

localStorage.clear();
sessionStorage.clear();
location.reload();

🛠️ Development

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   n8n Workflow   │    │   AI Service    │
│   (JavaScript)  │───▶│   (Node.js)      │───▶│   (OpenRouter)  │
├─────────────────┤    ├──────────────────┤    ├─────────────────┤
│ • Form handling │    │ • Input validation│    │ • Quiz generation│
│ • Quiz logic    │    │ • AI integration │    │ • Content analysis│
│ • Score tracking│    │ • Response parsing│    │ • Multi-language │
│ • State mgmt    │    │ • Error handling │    │ • Quality control│
└─────────────────┘    └──────────────────┘    └─────────────────┘

🔧 Key Classes & Methods

MemocardQuiz Class

class MemocardQuiz {
  // Core Methods
  init()                    // Initialize based on current page
  handleQuizGeneration()    // Process form submission
  generateQuiz()           // API communication
  displayQuestion()        // Render current question
  selectAnswer()           // Handle answer selection
  updateNavigationButtons() // Control quiz navigation
  finishQuiz()             // Calculate and store results
  displayResults()         // Show final score and analytics
}

📈 Performance Optimizations

Lazy Loading: Questions loaded on-demand
Local Storage: Efficient state persistence
Debounced Validation: Real-time input validation
Fallback Systems: Multiple error recovery methods

🧪 Testing Strategy

Unit Tests: Individual function testing
Integration Tests: API workflow validation
E2E Tests: Complete user journey
Performance Tests: Load and response time
Cross-browser Tests: Compatibility verification

🚀 Deployment Options

Static Hosting (GitHub Pages, Netlify, Vercel)

# Build and deploy
npm run build
npm run deploy

Docker Container

FROM nginx:alpine
COPY . /usr/share/nginx/html
EXPOSE 80

CDN Integration

Tailwind CSS via CDN
Optional: Bundle and minify for production
Service Worker for offline capability

🤝 Contributing

Development Setup

Clone repository: git clone <repo-url>
Install dependencies: npm install (if using build tools)
Start development server: npm run dev or open index.html
Configure n8n: Follow setup instructions above

Code Style

JavaScript: ES6+ features, async/await
HTML: Semantic structure, accessibility
CSS: Tailwind utility classes, BEM methodology
Comments: JSDoc format for functions

Pull Request Process

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

📄 License

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

Attribution

Tailwind CSS: UI styling framework
OpenRouter: AI model integration
n8n: Workflow automation platform

🌟 Quick Links

📖 Setup Guide - Quick start instructions
🔧 Troubleshooting - Common issues and fixes
🤖 n8n Workflow - Import this into your n8n instance
🎯 Live Demo - Try it online

Made with ❤️ for educational excellence

🛠️ n8n Workflow

Visual representation of the AI-powered quiz generation workflow implemented in n8n.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.vscode		.vscode
assets		assets
MemCards.json		MemCards.json
README.md		README.md
index.html		index.html

Worketyamo-Students/Memocards-deploy

Folders and files

Latest commit

History

Repository files navigation