medienkompetenz-lernplattform/backend/lessons/README.md

Lessons Directory

This directory contains all lesson content for the security awareness training platform.

Structure

lessons/
├── configs/                    # YAML lesson configurations
│   ├── phishing-email-basics.yaml
│   ├── sql-injection-shop.yaml
│   └── browser-in-browser-attack.yaml
├── modules/                    # JavaScript lesson modules
│   ├── base/
│   │   └── LessonModule.js    # Base class all lessons extend
│   ├── phishing-email-basics/
│   │   └── index.js
│   ├── sql-injection-shop/
│   │   └── index.js
│   └── browser-in-browser-attack/
│       └── index.js
├── lesson-schema.json         # JSON schema for validation (optional)
├── README.md                  # This file
└── LESSONS_DOCUMENTATION.md   # Comprehensive lesson docs

Available Lessons

1. Phishing Email Detection Basics

• Key: phishing-email-basics
• Difficulty: Beginner
• Duration: 15 minutes
• Topics: Email security, social engineering, red flags
• Interactive: No

2. SQL Injection Attack - Online Shop Demo

• Key: sql-injection-shop
• Difficulty: Intermediate
• Duration: 20 minutes
• Topics: Web security, OWASP Top 10, SQL injection
• Interactive: Yes - Fake shop with vulnerable search

3. Browser-in-the-Browser (BitB) Attack

• Key: browser-in-browser-attack
• Difficulty: Advanced
• Duration: 25 minutes
• Topics: Advanced phishing, OAuth security, UI spoofing
• Interactive: Yes - Fake browser popup demos

Quick Start

Adding a New Lesson

1. Create YAML config:

   cp configs/phishing-email-basics.yaml configs/your-lesson.yaml
   # Edit the file with your lesson content
   

2. Create module:

   mkdir modules/your-lesson
   # Create index.js extending LessonModule
   

3. Seed to database:

   # Add to seed script
   docker exec lernplattform_backend node seed-lessons.js
   

4. Assign to event:

   • Use admin panel to assign lesson to events
   • Configure points, weight, and order

Testing a Lesson

1. Seed the lesson (see above)
2. Assign to a test event via admin panel
3. Join event as participant from hub page
4. Complete the lesson and verify:
   • All steps render correctly
   • Questions award proper points
   • Interactive components work
   • Score calculates correctly

Lesson Configuration Format

Minimal YAML Example

lessonKey: "my-lesson"
title: "My Lesson Title"
description: "Brief description"
difficultyLevel: "beginner"
estimatedDuration: 15
module: "my-lesson"

steps:
  - id: "intro"
    type: "content"
    title: "Introduction"
    content: "Lesson content here..."

  - id: "q1"
    type: "question"
    questionType: "single_choice"
    question: "What is the answer?"
    options:
      - id: "correct"
        text: "The right answer"
        isCorrect: true
        points: 100
      - id: "wrong"
        text: "Wrong answer"
        isCorrect: false
        points: 0
    maxPoints: 100
    feedback:
      correct: "Great job!"
      incorrect: "Try again!"

scoring:
  passingScore: 70
  maxTotalPoints: 100

Minimal Module Example

const LessonModule = require('../base/LessonModule');

class MyLesson extends LessonModule {
  constructor(config) {
    super(config);
  }

  // Use base class validation by default
  // Override only if custom logic needed
}

module.exports = MyLesson;

Question Types

Single Choice

• One correct answer
• Radio buttons in UI
• All-or-nothing scoring

Multiple Choice

• Multiple correct answers
• Checkboxes in UI
• Partial credit per correct selection

Free Text

• Open-ended response
• Keyword-based validation
• Minimum length requirement

Interactive Components

For lessons with interactive demos:

1. Define in YAML:

   - id: "demo"
     type: "interactive"
     title: "Interactive Demo"
     interactiveComponent: "MyComponent"
   

2. Provide data in module:

   getInteractiveData(stepId) {
     if (stepId === 'demo') {
       return { /* component data */ };
     }
     return null;
   }
   

3. Create React component:

   frontend/src/components/lessons/InteractiveContent/MyComponent.jsx
   

4. Register in LessonView.jsx

File Naming Conventions

• Lesson keys: lowercase-with-hyphens
• Config files: {lesson-key}.yaml
• Module directories: {lesson-key}/
• Module entry: index.js

Best Practices

Content

• Start with clear learning objectives
• Use real-world examples
• Progress from easy to hard
• Provide immediate feedback
• Make it hands-on when possible

Questions

• 2-4 options for choice questions
• Clear, unambiguous wording
• Educational feedback (not just "correct"/"incorrect")
• Points reflect difficulty

Code

• Extend LessonModule base class
• Use base class methods when possible
• Comment complex logic
• Handle errors gracefully
• Validate all inputs

Security

• Never execute actual dangerous commands
• Sandbox all demonstrations
• Use appropriate warnings
• Don't leak sensitive data

Common Patterns

Multi-step Content Lesson

steps:
  - type: content (intro)
  - type: content (main content)
  - type: question
  - type: content (summary)
  - type: question

Interactive Demo Lesson

steps:
  - type: content (intro)
  - type: interactive (hands-on)
  - type: question (about demo)
  - type: content (explanation)
  - type: question (best practices)

Progressive Learning

# Start easy
- Single choice with obvious answer
# Build complexity
- Multiple choice with several correct answers
# Test understanding
- Free text requiring explanation

Troubleshooting

Lesson not appearing in admin panel

• Check if lesson was seeded to database
• Verify lesson_key matches between YAML and database
• Check database logs for errors

Questions not scoring correctly

• Verify maxPoints matches sum of correct option points
• For multiple choice, ensure points are on correct options
• Check isCorrect boolean values

Interactive component not loading

• Verify component name matches in YAML
• Check component is imported in LessonView.jsx
• Look for console errors in browser
• Verify getInteractiveData() returns data

Module not found errors

• Check module_path in database matches directory name
• Verify index.js exists in module directory
• Ensure module.exports is present
• Check for syntax errors in module

Documentation

• Comprehensive Guide: LESSONS_DOCUMENTATION.md
• Base Class: modules/base/LessonModule.js
• Examples: See existing lessons in configs/ and modules/

Development Workflow

1. Design lesson content and questions
2. Create YAML config and module
3. Test locally with seed script
4. Assign to test event
5. Validate all questions and interactions
6. Review scoring and feedback
7. Deploy to production event

Support

For questions or issues:

1. Review existing lesson implementations
2. Check base class documentation
3. Test in development environment first
4. Review error logs for debugging

---

Last Updated: 2026-01-12 Total Lessons: 3 Platform Version: 1.0.0