Josh Bruce Online

Product Design Study App - Developer Guide

📋 Overview

This is a single-page web application for studying Product Design coursework. It’s built with vanilla JavaScript, HTML, and CSS (no frameworks) and includes Firebase authentication and Firestore database for progress tracking. The app provides five study modes: flashcards, quiz questions, long questions, time trials, and Topic Targets (AI-powered personalized practice).

✅ Latest Additions

🏗️ Architecture

Core Files

Data Structure

/product_design/
  /flashcards/          # JSON files with Q&A flashcards for each topic
  /topic_questions/     # JSON files with multiple-choice questions
  /long_questions/      # JSON files with extended response questions (optional)
  /papers/              # Past papers (not currently used in UI)
  /mark_schemes/        # Mark schemes (not currently used in UI)

🔥 Firebase Integration

Services Used

  1. Firebase Authentication - Google Sign-In
  2. Cloud Firestore - User progress tracking

External helpers

Configuration

Located at top of app.js:

Firestore Data Structure

users/{userId}/
  - profile: {
      displayName: string,
      email: string,
      photoURL: string,
      lastActivity: timestamp,
      updatedAt: timestamp
    }
  - streak: {
      current: number,
      longest: number,
      lastStudyDate: 'YYYY-MM-DD',
      updatedAt: timestamp
    }

  /progress/{topicId}
    - flashcards: {
        [cardId]: {
          confidence: "easy" | "medium" | "hard",
          lastReviewed: timestamp,
          reviewCount: number
        }
      }
    - questions: {
        [questionId]: {
          correct: boolean,
          lastAttempted: timestamp,
          attemptCount: number,
          correctCount: number
        }
      }
    - metadata: {
        lastUpdated: timestamp
      }

  /sessions/{sessionId}  // Study session logging (reserved for future use)

leaderboards/
  weekly: {
    generatedAt: timestamp,
    rangeStart: timestamp,
    entries: [
      {
        userId: string,
        displayName: string,
        photoURL: string | null,
        totalScore: number,
        totalSessions: number,
        breakdown: { [sessionType: string]: number }
      }
    ]
  }

Key Features

🎨 Design System

Colors

Topic Colors

6 pastel rainbow colors assigned cyclically to topics:

pastelColors: [
  '#E57373', // Soft Red
  '#FFB74D', // Soft Orange
  '#FFD54F', // Soft Yellow
  '#81C784', // Soft Green
  '#64B5F6', // Soft Blue
  '#BA68C8', // Soft Purple
]

Key Design Elements

🔐 Authentication & User Management

Authentication Flow

  1. User clicks “Sign in with Google”
  2. Firebase popup authentication
  3. User data stored in app.currentUser
  4. UI updates to show user info
  5. Progress data loaded from Firestore

User Interface

Key Functions

📚 Content Structure

10 Topics

Each topic has metadata in app.topicMeta object:

  1. Materials (Topic 1) - Flashcards ✓ Questions ✓
  2. Performance Characteristics (Topic 2) - Flashcards ✓ Questions ✓
  3. Processes & Techniques (Topic 3) - Flashcards ✓ Questions ✓ (150 questions)
  4. Digital Technologies (Topic 4) - Flashcards ✓ Questions ✓
  5. Factors Influencing Development (Topic 5) - Flashcards ✓ Questions ✓
  6. Effects of Technological Developments (Topic 6) - Flashcards ✓ Questions ✓
  7. Safe Working Practices & Risk Assessment (Topic 7) - Flashcards ✓ Questions ✓
  8. Features of Manufacturing Industries (Topic 8) - Flashcards ✓ Questions ✓
  9. Designing for Maintenance & Environment (Topic 9) - Flashcards ✓ Questions ✓
  10. Exam Tips - Flashcards ✓

Each topic can have:

Data Preloading

🎮 Study Modes

1. Flashcards Mode

2. Quiz Questions Mode

3. Long Questions Mode

4. Time Trials Mode

5. Topic Targets Mode ⭐ NEW

Quick Access

🧭 Navigation System

Screen Management

Screen Flow

landing-screen (homepage)
  ↓ select topic
mode-screen (flashcards, questions, or long questions)
  ↓ select mode
flashcard-screen OR question-screen OR long-question-screen
  ↓ complete
results-screen (questions only)

OR

landing-screen
  ↓ click Time Trials
time-trials-settings-screen
  ↓ configure & start
time-trials-countdown-screen (3-2-1)
  ↓ auto-advance
time-trials-quiz-screen
  ↓ time up
time-trials-results-screen

OR

landing-screen
  ↓ click account button
account-screen
  ↓ view profile, theme, progress breakdown

OR ⭐ NEW

landing-screen
  ↓ click Topic Targets (signed in only)
topic-targets-screen
  ↓ complete personalized practice
landing-screen (auto-return after completion)

All Screens (12 total)

  1. landing-screen - Homepage with topic cards
  2. mode-screen - Study mode selection
  3. flashcard-screen - Flashcard study
  4. question-screen - Quiz questions
  5. long-question-screen - Extended response questions
  6. results-screen - Quiz results
  7. time-trials-settings-screen - Time trials configuration
  8. time-trials-countdown-screen - 3-2-1 countdown
  9. time-trials-quiz-screen - Time trials quiz
  10. time-trials-results-screen - Time trials results
  11. account-screen - User profile and settings
  12. topic-targets-screen - Personalized practice ⭐ NEW

🎯 State Management

App Object (app)

Centralized state in app.js:

{
  // User
  currentUser: null,
  darkMode: false,

  // Navigation
  currentScreen: 'landing',
  currentTopic: null,
  currentTopicColor: null,
  currentMode: null,
  currentIndex: 0,

  // Data
  topics: [],
  flashcards: [],
  questions: [],
  longQuestions: [],
  topicDataCache: {},  // Preloaded topic data for instant access

  // Session
  score: 0,
  totalAnswered: 0,
  sessionProgress: {},
  quizAnswers: [],
  quizStartTime: null,
  quizEndTime: null,

  // Flashcard progress (batched syncing)
  flashcardProgressQueue: {},
  progressSyncTimeout: null,

  // Topic Breakdown Cache (5-minute TTL) ⭐ NEW
  topicBreakdownCache: {
    data: null,           // Cached HTML string
    timestamp: null,      // When cache was created
    maxAge: 5 * 60 * 1000 // 5 minutes in milliseconds
  },

  // Topic Targets ⭐ NEW
  topicTargets: {
    flashcards: [],      // Selected flashcards (5 total: 1 easy, 2 medium, 2 hard)
    questions: [],       // Selected questions (5 total: 4 wrong, 1 correct)
    currentIndex: 0,
    currentType: null,   // 'flashcard' or 'question'
    score: 0,
    totalAnswered: 0
  },

  // Time Trials
  timeTrials: { ... }
}

Data Manager (dataManager)

Firestore operations module with helper functions:

Collection Management:

User Operations:

Progress Operations:

Preferences:

Progress Syncing Strategy

  1. Flashcards: Queued and batched every 2 seconds to reduce writes
  2. Quiz Questions: Saved immediately after each answer
  3. Force Sync: On navigation away from flashcard screen
  4. Data Reconstruction: Converts Firestore flat keys to nested objects
  5. Cache Invalidation: Topic breakdown cache cleared when progress changes ⭐ NEW
  6. Offline Support: Firestore persistence allows offline progress tracking

🎨 UI Components

Topic Cards

Mode Cards

Topic Targets Button ⭐ NEW

Anki Export

Account Page Features

Profile Section

Theme Selection

Topic Breakdown

Progress Bars

⌨️ Keyboard Shortcuts

Flashcards

Questions

Long Questions

Time Trials

📱 Responsive Design

Breakpoints

Container

Mobile Optimizations

🔧 Performance Optimizations

Data Loading

Firestore Optimization

Event Handling

Animations

🎯 Design Philosophy

Principles

User Experience

🐛 Known Issues & Considerations

Firestore Data Structure

Progress Data

Anki Export Limitations

🔄 Common Tasks

Adding a New Topic

  1. Add flashcards JSON to /product_design/flashcards/
  2. Add questions JSON to /product_design/topic_questions/
  3. (Optional) Add long questions JSON
  4. Add entry to app.topicMeta object in app.js: 
    'topic_id': {
    name: 'Topic Name',
    flashcardsFile: 'path/to/flashcards.json',
    questionsFile: 'path/to/questions.json',
    longQuestionsFile: 'path/to/long_questions.json' // optional
}
  5. Topic will auto-appear on homepage

Adding Long Questions to Existing Topic

  1. Create JSON file in /product_design/long_questions/
  2. Format: 
    [
  {
    "id": 1,
    "question": "Your question here",
    "answer": "Model answer here",
    "subtopic": "Optional subtopic"
  }
]
  3. Update topicMeta with longQuestionsFile path
  4. Long questions card will appear in mode selection

Modifying Theme Colors

Customizing Progress Analytics

Working with Topic Targets ⭐ NEW

Key Functions:

Selection Algorithm:

  1. Gather all progress data from Firestore
  2. Group flashcards by confidence (easy/medium/hard)
  3. Group questions by correctness (correct/incorrect)
  4. Select diverse set: 1 easy + 2 medium + 2 hard flashcards
  5. Select challenging set: 4 incorrect + 1 correct questions
  6. Fallback to random selection if insufficient progress data
  7. Combine and present in mixed order

Customization:

🚀 Getting Started

Running Locally

  1. Start a local server: python3 -m http.server 8002
  2. Open browser to http://localhost:8002
  3. Firebase auth requires proper domain configuration
  4. Sign in with Google to enable progress tracking

File Structure

/PD_learn/
  index.html              # Main HTML
  app.js                  # All JavaScript
  styles.css              # All CSS
  favicon.svg             # App icon
  /product_design/        # Study content
    /flashcards/          # Flashcard JSON files
    /topic_questions/     # Question JSON files
    /long_questions/      # Long question JSON files
  2claude.md              # This file

Dependencies

Environment Setup

💡 Tips for Next Developer

Code Quality

  1. Console logging: Extensive emoji-prefixed logs for debugging
  2. Error handling: Try-catch blocks with detailed error logs
  3. Type checking: Validate data before Firestore operations
  4. State management: Centralized in app object

Firestore Best Practices

  1. Batch writes: Use for multiple related updates
  2. Dot notation: Efficient for nested field updates
  3. Merge operations: Preserve existing data
  4. Data validation: Check structure before saving

UI/UX Considerations

  1. Loading states: Show feedback during async operations
  2. Error messages: User-friendly error handling
  3. Accessibility: Keyboard navigation, ARIA labels
  4. Responsive: Test on various screen sizes

Performance

  1. Preload data: Background loading for instant access
  2. Cache aggressively: In-memory topic data cache
  3. Batch operations: Reduce Firestore write costs
  4. Optimize queries: Minimize database reads

Security

  1. Firestore rules: Configure proper read/write permissions
  2. Auth validation: Check user state before operations
  3. Input sanitization: Validate user inputs
  4. API keys: Don’t commit sensitive credentials

📝 Code Style

🔍 Debugging

Browser Console

Common Issues

  1. Firebase errors: Check network tab, auth state, Firestore rules
  2. Progress not saving: Check user is signed in, console for errors
  3. Data not loading: Verify JSON file paths in topicMeta
  4. Styling issues: Check CSS custom properties, theme state
  5. Navigation stuck: Check app.currentScreen in console

Debug Helpers

🎉 Recent Updates

Latest Release (Current)

⭐ NEW: Topic Targets - Personalized Practice Mode

Cache & Performance Enhancements

Previous Major Features

  1. Long Questions Mode - Extended response practice with model answers
  2. Anki Export - Download flashcards for Anki import
  3. Topic Breakdown - Visual progress analytics per topic
  4. Dark Mode - Full dark theme with WCAG AA compliance
  5. Progress Syncing - Cloud sync via Firestore
  6. Account Page - Profile management and analytics
  7. Time Trials - Timed quiz mode with multi-topic support

Performance Improvements

UI Enhancements

The app is production-ready with robust cloud syncing, comprehensive analytics, AI-powered personalized practice, and a polished user experience. 🎉