Skip to content

INTERACTIVE_MODULE_CREATION_GUIDE.md

Latest commit

 

History

History
387 lines (317 loc) · 12.1 KB

INTERACTIVE_MODULE_CREATION_GUIDE.md

File metadata and controls

387 lines (317 loc) · 12.1 KB
Raw

Interactive Module Creation Guide for MathGaling ITS

Overview

This guide documents the complete process for creating interactive DepEd-aligned modules in the MathGaling Intelligent Tutoring System. Follow this systematic approach to add new modules with proper database integration, frontend components, and educational content.

1. Module Planning & Content Preparation

A. Gather DepEd Curriculum Data

  1. Identify Knowledge Components (KCs) from DepEd curriculum
  2. Extract MELC codes (e.g., M3NS-Ia-9.1, M3NS-Ib-5.1-2)
  3. Collect learning objectives and detailed content
  4. Document practice activities and real-world contexts
  5. Note Filipino terminology and cultural elements

B. Module Structure Design

Module X: [Filipino Title]
├── KC#: [Knowledge Component Title]
│   ├── Learning Objectives
│   ├── Key Concepts
│   ├── Practice Activities
│   └── Assessment Criteria
└── KC#: [Next Knowledge Component]

Example Modules Created:

  • Module 1: Numero At Ang Kahulugan Nito (KC1, KC2, KC3)
  • Module 2: Paghahambing at Pagkakaayos ng mga Numero (KC4, KC5, KC6)
  • Module 3: Ordinal Numbers at Pera (KC7, KC8)

2. Database Schema Implementation

A. Create/Update Seed Script

File: /scripts/fix-seed-deped-modules-safe.sql

B. Module Entry Structure

-- Insert new module
INSERT INTO deped_modules (quarter_id, module_number, title, description, estimated_weeks, order_index, is_active) VALUES
(
    (SELECT id FROM deped_quarters WHERE quarter_number = X AND grade_level = 3),
    MODULE_NUMBER,
    'Module Title in Filipino',
    'English description of module content',
    ESTIMATED_WEEKS,
    ORDER_INDEX,
    true
);

C. Learning Competencies Structure

-- Insert competencies for each KC
INSERT INTO learning_competencies (module_id, melc_code, competency_text, learning_objectives, difficulty_level) VALUES
(
    module_id,
    'MELC_CODE',
    'KC#: Knowledge Component Title',
    ARRAY[
        'Learning objective 1',
        'Learning objective 2',
        '...'
    ],
    DIFFICULTY_LEVEL
);

D. Quarter Management

  • Quarter 1: Modules 1, 2 (Unang Markahan)
  • Quarter 2: Module 3+ (Ikalawang Markahan)
  • Auto-create quarters if they don't exist

3. Frontend Component Implementation

A. ModuleLearningView.js Structure

Module Content Object Pattern

const moduleContent = {
  MODULE_NUMBER: {
    title: "Module X: Filipino Title",
    description: "English description",
    lessons: [
      {
        id: KC_NUMBER,
        title: "KC#: Knowledge Component Title",
        melc_code: "MELC_CODE",
        steps: [
          {
            type: "introduction|explanation|interactive|practice",
            title: "Step Title",
            content: "Step content with markdown support",
            visual: "🔢", // Emoji icon
            // Additional properties based on type
          }
        ]
      }
    ]
  }
};

Step Types and Properties

  1. Introduction Steps:
{
  type: "introduction",
  title: "Welcome Message",
  content: "Motivating introduction content",
  visual: "🎯"
}
  1. Explanation Steps:
{
  type: "explanation", 
  title: "Concept Explanation",
  content: "Detailed rules and concepts with markdown",
  visual: "📍",
  example: {
    number: "Example title",
    breakdown: [
      { step: "Step 1", check: "What to check", result: "Outcome" },
      { position: "21st", filipino: "Ika-dalawampu't isa", rule: "ends in 1 → st" },
      { format: "Symbol form", result: "PhP 36.75", explanation: "Use PhP notation" }
    ],
    fullWords: "Complete example in words",
    ascending: "Ordered sequence",
    numbers: "Number list"
  }
}
  1. Interactive Steps:
{
  type: "interactive",
  title: "Interactive Challenge",
  question: "Question text here?",
  hint: "Helpful hint for students",
  correctAnswer: "EXACT_ANSWER",
  options: ["Option 1", "Option 2", "Option 3", "Option 4"],
  explanation: "Why this answer is correct"
}
  1. Practice Steps:
{
  type: "practice",
  title: "Practice Exercise", 
  content: "Practice context",
  question: "Practice question?",
  hint: "Practice hint",
  correctAnswer: "ANSWER",
  explanation: "Detailed explanation"
}

B. Module Logic Updates

Module Detection Logic

// Update quarter assignment
quarter_number: moduleId === "1" ? 1 : moduleId === "2" ? 1 : 2,
estimated_weeks: moduleId === "1" ? 3 : moduleId === "2" ? 4 : 3,

Navigation and Progress

  • All functions use moduleContent[moduleId] for dynamic content
  • Progress calculation across all steps in all lessons
  • Proper step and lesson advancement logic

4. Dashboard Integration

A. DepEdModuleDashboard.js Updates

Module Accessibility (Development)

// Allow access to implemented modules for testing
const isAccessible = module.module_number <= 3 || index === 0 || previousModule?.is_completed || module.completion_percentage > 0;

Debug Information

// Add debug logging for module fetching
console.log('Fetched DepEd modules:', modulesResponse.data);
console.log('Module count:', modulesResponse.data.length);

B. API Endpoint Integration

  • Netlify Function: /api/students/:id/deped-modules
  • View: deped_module_overview includes all modules automatically
  • Progressive Loading: Fetches from database view with competency counts

5. Educational Design Patterns

A. Filipino Cultural Integration

  1. Language: Extensive Filipino terminology

    • Ordinal: "ika-", "una", "ikalawa"
    • Money: "piso", "sentimo", "at"
    • Directions: "pataas", "pababa"

  2. Cultural Contexts:

    • Philippine heroes on currency
    • Filipino alphabet (28 letters with NG, Ñ)
    • Local scenarios (schools, markets, holidays)

  3. Real-World Applications:

    • Tree planting comparisons
    • Market weight ordering
    • Birthday celebrations
    • Shopping scenarios

B. Scaffolded Learning Design

  1. Introduction: Motivating context with visual icons
  2. Explanation: Detailed rules with structured examples
  3. Interactive: Guided practice with immediate feedback
  4. Practice: Independent application with hints

C. Assessment & Feedback

  • Immediate Feedback: 4-second display with explanations
  • Positive Reinforcement: "🎉 Excellent!" for correct answers
  • Gentle Correction: Hints and proper solutions for errors
  • Auto-Advancement: Seamless progression through content

6. File Structure & Organization

A. Core Files Modified

/client/src/components/student/
├── ModuleLearningView.js          # Main interactive tutoring component
├── ModuleLearningView.css         # Styling for tutoring interface
└── DepEdModuleDashboard.js        # Module selection dashboard

/scripts/
└── fix-seed-deped-modules-safe.sql # Database setup script

/netlify/functions/
└── api.js                         # API endpoints (already configured)

B. Documentation Files

/
├── MODULE_1_IMPLEMENTATION.md
├── MODULE_2_IMPLEMENTATION.md  
├── MODULE_3_IMPLEMENTATION.md
└── INTERACTIVE_MODULE_CREATION_GUIDE.md (this file)

7. Testing & Quality Assurance

A. Build Verification

npm run build
# Verify no compilation errors
# Check bundle size increase is reasonable

B. Functionality Testing

  1. Database Setup: Run SQL script successfully
  2. Dashboard Display: Module appears in correct quarter
  3. Navigation: /student/module/X routes properly
  4. Content Flow: All steps advance correctly
  5. Interactions: Questions and feedback work properly
  6. Cultural Elements: Filipino terms display correctly

C. Educational Validation

  • MELC Alignment: Content matches curriculum codes
  • Age Appropriateness: Grade 3 cognitive level suitable
  • Cultural Sensitivity: Respectful Filipino integration
  • Learning Progression: Logical step-by-step advancement

8. Common Patterns & Best Practices

A. Content Structure Patterns

  1. Always start with introduction for context setting
  2. Use visual icons consistently across step types
  3. Include Filipino terminology with English explanations
  4. Provide real-world contexts familiar to students
  5. Structure examples with clear breakdowns

B. Technical Implementation

  1. Dynamic property handling in example rendering
  2. Consistent step type logic across all modules
  3. Proper quarter assignment based on module number
  4. Debug logging for development troubleshooting
  5. Scalable architecture for unlimited module addition

C. Database Best Practices

  1. Use DO $$ blocks for safe script execution
  2. Check existence before inserting records
  3. Handle conflicts with proper deletion/re-insertion
  4. Include verification queries for confirmation
  5. Join tables properly for complex queries

9. Module Creation Checklist

Pre-Development

  • DepEd curriculum data collected and organized
  • MELC codes identified and validated
  • Filipino terminology researched and verified
  • Real-world contexts planned and culturally appropriate

Database Implementation

  • Module entry added to seed script
  • Learning competencies defined with objectives array
  • Quarter assignment configured correctly
  • Verification queries updated to include new module

Frontend Development

  • Module content object structured properly
  • All step types implemented (intro, explanation, interactive, practice)
  • Filipino cultural elements integrated throughout
  • Example breakdowns use appropriate property names
  • Module logic updated for new module number

Dashboard Integration

  • Module accessibility updated in DepEdModuleDashboard
  • Debug logging confirms module fetching
  • Quarter navigation works properly
  • Progressive access maintains educational sequence

Testing & Validation

  • Build compiles without errors
  • Database script executes successfully
  • Module appears in dashboard under correct quarter
  • Navigation to module works properly
  • All interactive elements function correctly
  • Cultural content displays appropriately
  • Educational progression flows logically

Documentation

  • Implementation documentation created
  • Technical patterns documented
  • Cultural elements explained
  • Testing results verified

10. Next Module Creation Template

Quick Start for Module 4+

  1. Copy Module 3 structure in ModuleLearningView.js
  2. Update module number, title, and quarter assignment
  3. Replace KC content with new curriculum data
  4. Add database entries to seed script
  5. Update dashboard accessibility for new module number
  6. Test full implementation following checklist
  7. Document new module following established patterns

Module Numbering Convention

  • Module 1-2: Quarter 1 (Foundation concepts)
  • Module 3+: Quarter 2+ (Advanced concepts)
  • KC Numbering: Sequential (KC7, KC8, KC9, KC10...)
  • MELC Codes: Match official DepEd curriculum

Summary

This guide provides the complete framework for creating interactive, culturally-authentic, DepEd-aligned modules in the MathGaling Intelligent Tutoring System. Each module follows consistent patterns while allowing for unique educational content and cultural integration. The system is designed for scalability and maintains high educational standards throughout the development process.

Current Status: 3 modules implemented (9 knowledge components total) Next Steps: Follow this guide to add Module 4+ with additional DepEd curriculum content