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:**
   ```bash
   cp configs/phishing-email-basics.yaml configs/your-lesson.yaml
   # Edit the file with your lesson content
   ```

2. **Create module:**
   ```bash
   mkdir modules/your-lesson
   # Create index.js extending LessonModule
   ```

3. **Seed to database:**
   ```bash
   # 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

```yaml
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

```javascript
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:**
   ```yaml
   - id: "demo"
     type: "interactive"
     title: "Interactive Demo"
     interactiveComponent: "MyComponent"
   ```

2. **Provide data in module:**
   ```javascript
   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
```yaml
steps:
  - type: content (intro)
  - type: content (main content)
  - type: question
  - type: content (summary)
  - type: question
```

### Interactive Demo Lesson
```yaml
steps:
  - type: content (intro)
  - type: interactive (hands-on)
  - type: question (about demo)
  - type: content (explanation)
  - type: question (best practices)
```

### Progressive Learning
```yaml
# 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](./LESSONS_DOCUMENTATION.md)
- **Base Class:** [modules/base/LessonModule.js](./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