Instruction file imported from uybinhphan/quiz-abic (.cursor/rules/quiz-app.mdc). Copyright stays with the author.

Quiz Application Documentation

Project Structure

quiz-nghiep-vu/
├── index.html # Main client-side application
├── js/ # Directory for JavaScript modules
│ ├── app.js # Main application logic and orchestrator
│ ├── config.js # Configuration constants
│ ├── dom-elements.js # DOM element references
│ ├── quiz-core.js # Core quiz logic (navigation, answers, results)
│ ├── quiz-service.js # Service for loading quiz data and manifest
│ ├── service-worker-loader.js # Service worker registration
│ ├── state.js # Application state management
│ ├── swipe.js # Swipe navigation handling
│ ├── theme.js # Theme (light/dark) management
│ └── ui-helpers.js # UI utility functions (modals, view changes)
├── convert.js # Excel to JSON conversion script
├── compress-json.js # JSON optimization script
├── data/ # Generated JSON files directory
│ └── quiz_manifest.json # Auto-generated quiz manifest
├── quizzes/ # Source Excel files directory
├── service-worker.js # PWA service worker for caching/offline support
├── README.md # Project documentation
└── .github/workflows/ # CI/CD configuration files
├── release.yml # Release automation workflow
├── deploy.yml # Deployment workflow
└── pr-review.yml # PR validation workflow

Client-Side Application (index.html)

Core Requirements

• Single-page web application using pure HTML, CSS, and JavaScript.
• JavaScript is structured using ES6 modules located in the js/ directory.
• The main entry point for JavaScript is js/app.js, loaded via <script type="module" src="js/app.js" defer></script>.
• No external frameworks (React, Vue, Angular).
• Uses canvas-confetti via CDN for visual effects.
• Fully client-side, suitable for static hosting.
• Progressive Web App (PWA) features with service worker support.
• Vietnamese as primary interface language.

Data Structure

• Quiz manifest: data/quiz_manifest.json

  [
    {
      "name": "Display Name",
      "file": "data/quiz_filename.json",
      "size": 12345
    }
  ]

• Quiz data files: data/*.json

  {
    "originalDisplayName": "Display Name",
    "questions": [
      {
        "question": "Question text?",
        "options": ["Option 1", "Option 2", "Option 3", "Option 4"],
        "correctAnswerIndex": 0,
        "source": "Optional source text"
      }
    ]
  }

UI Components

• Quiz selection screen with:
  • Quiz list (dropdown menu)
  • Shuffle checkbox
  • Quiz title display
• Quiz interface with:
  • Question display
  • Answer buttons
  • Progress indicator
  • Score display
  • Navigation controls
  • Settings menu
  • Timer functionality
• Results screen with:
  • Final score
  • Performance statistics
  • Confetti effect
  • Action buttons
• Review mode with:
  • Question navigation
  • Answer highlighting
  • Filter toggle (view all questions or only wrong answers)
  • Source display

State Management

• Uses localStorage (key: 'quizAppState')
• Saves state on significant actions
• Handles session resumption via modal
• Clears state on intentional exit
• In-memory caching to prevent redundant data fetching

Styling

• Responsive design with media queries
• Light/dark theme using CSS variables
• Persistent theme preference storage
• Clean, modern layout
• Proper spacing and positioning
• Support for Vietnamese character encoding (UTF-8)

Data Conversion Script (convert.js)

Dependencies

• Node.js
• xlsx library (npm install xlsx)

Input Format

Excel files in ./quizzes/ with columns:

• B: Câu hỏi (Required)
• C: Đáp án 1 (Required)
• D: Đáp án 2 (Required)
• E: Đáp án 3 (Required)
• F: Đáp án 4 (Required)
• G: Đáp án đúng (Required, 1-4)
• H: Trích dẫn nguồn (Optional)

Processing Rules

• Skip temporary Excel files (~$*)
• Validate required fields
• Convert 1-based to 0-based answer indices
• Handle errors gracefully
• Generate properly formatted JSON
• Slugify filenames for web compatibility

Data Optimization (compress-json.js)

Processing

• Minifies JSON files (removes whitespace)
• Updates manifest file paths
• Adds file size information to manifest
• Outputs to ./data-compressed directory

Optimization Pipeline

JSON Compression

• Compression script for reduced file sizes
• Command: npm run compress

Asset Optimization

• HTML minification
• CSS minification
• Combined optimization process: npm run build

CI/CD Pipeline

Release Workflow

• Automatic versioning using semantic versioning
• Changelog generation based on commit messages
• Git tag creation for each release
• Triggered when PRs are merged to main

Deployment

• Automated deployment to GitHub Pages
• Minification and optimization of assets
• Zero-downtime deployment

Development Guidelines

Code Style

• Use meaningful variable names
• Include descriptive comments
• Follow consistent formatting
• Handle errors appropriately
• Use semantic commit messages

Testing

• Test Excel file processing
• Verify JSON output format
• Check client-side functionality
• Validate state persistence
• Test responsive design

Performance

• Optimize JSON file sizes
• Minimize DOM operations
• Use efficient event handlers
• Cache DOM references
• Lazy loading of non-essential resources

Security

• Sanitize user inputs
• Validate file paths
• Handle fetch errors
• Protect against XSS

Accessibility

• Use semantic HTML
• Provide keyboard navigation
• Include ARIA attributes
• Ensure color contrast

Browser Support

• Target modern browsers (Chrome, Firefox, Safari, Edge)
• Mobile browsers on iOS and Android
• Use feature detection
• Provide fallbacks

Offline Support

• Service worker for offline capability
• Client-side caching
• Offline-first approach when possible

Localization

• UI text and labels in Vietnamese
• Error messages and instructions in Vietnamese