Ejo App - Complete Documentation

Version: 1.0.0 | Last Updated: January 2025

1. Overview

Ejo is a polyglot language learning application designed to help users learn Kinyarwanda, French, and Spanish through interactive quizzes and flashcards. The app features instant feedback, scoring, leaderboards, and a beautiful, responsive UI—all without requiring a backend server.

2. Technologies Used

3. Architecture

3.1 File Structure

ejo-app/
├── index.html              # Landing page
├── shared.css              # Brand colors & CSS variables
├── components.css          # Reusable UI components
├── landing.css/js          # Landing page specific
├── quiz/                   # Quiz module
│   ├── quiz.html
│   ├── script.js           # Quiz logic & confetti
│   ├── styles.css
│   └── leaderboardManager.js
├── flashcards/             # Flashcard module
│   ├── flashcards.html
│   ├── flashcards.js       # Flashcard & quiz logic
│   ├── flashcards.css
│   └── flashcards.json     # Kinyarwanda vocabulary
├── questions/              # Quiz questions
│   ├── french.json
│   ├── spanish.json
│   └── ikinyarwanda.json
├── survey/                 # Feedback form
│   ├── survey.html         # JS inlined
│   └── survey.css
└── images/                 # Assets
            

3.2 Design Patterns

• Component-Based UI: Shared header, footer, and card components across all pages
• Module Pattern: ES6 modules for code organization
• Class-Based: QuizApp and LeaderboardManager classes
• Event-Driven: DOM event listeners for user interactions

4. Features

4.1 Quiz Mode

• Multiple-choice questions with 4 options
• 3 difficulty levels: Easy, Medium, Hard
• Timed questions (8-10 seconds based on difficulty)
• Real-time scoring (+5 correct, -1 incorrect)
• Progress bar and question counter
• Auto-end after 5 wrong answers
• Confetti animation for high scores

4.2 Flashcards

• Interactive flip cards with Kinyarwanda vocabulary
• Front: Word, phonetics, meaning
• Back: Example sentence
• Navigation: Previous, Next, Skip, Go to card #
• Search functionality
• Quiz mode based on viewed cards
• Keyboard shortcuts (Arrow keys, Space/Enter)

4.3 Leaderboard

• Top 10 scores stored in localStorage
• Player name persistence
• Separate leaderboards for quiz and flashcard modes
• Date tracking for each score

5. Navigation Guide

5.1 Keyboard Shortcuts

Flashcards:

• ← Previous card
• → Next card
• Space or Enter Flip card
• S Skip to random card

6. Data Management

6.1 LocalStorage Keys

• ejo_leaderboard - Quiz leaderboard data
• ejo_player_name - Quiz player name
• flashcard_leaderboard - Flashcard quiz scores
• flashcard_player_name - Flashcard player name

6.2 JSON Data Format

Quiz Questions:

{
  "id": 1,
  "name": "French Quiz",
  "questions": [
    {
      "id": 1,
      "question": "How do you say 'Hello' in French?",
      "choices": ["Bonjour", "Gracias", "Ciao", "Hola"],
      "correctAnswer": "Bonjour",
      "explanation": "Bonjour is the French word for Hello"
    }
  ]
}

Flashcards:

{
  "flashcards": [
    {
      "id": 1,
      "kinyarwandaWord": "Muraho!",
      "meaning": "Hello!",
      "category": "greetings",
      "phonetics": "mu-ra-ho",
      "example": "Muraho! Aba hano?"
    }
  ]
}

7. Customization

7.1 Brand Colors

Edit shared.css to change colors globally:

:root {
    --ejo-primary: #FF6B6B;    /* Red */
    --ejo-secondary: #4ECDC4;  /* Teal */
    --ejo-accent: #FFE66D;     /* Yellow */
    --ejo-dark: #2A2A2A;       /* Dark gray */
    --ejo-light: #F7F7F7;      /* Light gray */
}

7.2 Adding Questions

1. Open the appropriate JSON file in questions/
2. Add new question object with unique ID
3. Follow the existing format
4. Questions 1-10: Easy, 11-35: Medium, 36+: Hard

7.3 Adding Languages

1. Create new JSON file: questions/language.json
2. Update quiz/script.js loadQuestions() method
3. Add option to language selector in quiz.html

8. Limitations

9. Browser Compatibility

Browser	Minimum Version	Status
Chrome	90+	✅ Fully Supported
Firefox	88+	✅ Fully Supported
Safari	14+	✅ Fully Supported
Edge	90+	✅ Fully Supported

10. Accessibility

• ARIA labels on interactive elements
• Semantic HTML structure
• Keyboard navigation support
• Color contrast ratios meet WCAG AA standards
• Focus indicators on all interactive elements
• Screen reader friendly

11. Performance

• Load Time: < 2 seconds on 3G
• Bundle Size: ~50KB (excluding images)
• No Dependencies: Vanilla JavaScript only
• Lazy Loading: Questions loaded on demand

12. Troubleshooting

Quiz not loading questions?

• Check browser console for errors
• Verify JSON files are in correct location
• Ensure relative paths are correct

Leaderboard not saving?

• Check if localStorage is enabled
• Clear browser cache and try again
• Check storage quota (5-10MB limit)

Flashcards not flipping?

• Ensure JavaScript is enabled
• Check for console errors
• Try refreshing the page

13. Future Enhancements

• Audio pronunciation support
• Spaced repetition algorithm
• Progress tracking and analytics
• Social sharing features
• More languages (Swahili, German, etc.)
• Offline PWA support
• Backend integration for cloud sync

14. Credits & License

Developer: Benjamin Niyodusenga

Year: 2025

License: All rights reserved

Icons: Font Awesome (Free License)

Fonts: System fonts (Segoe UI, Roboto, etc.)

15. Contact & Support

For questions, feedback, or bug reports:

• GitHub: @benduse
• Twitter: @Nbenduse
• LinkedIn: Benjamin Niyodusenga
• Feedback Form: Submit Feedback