medienkompetenz-lernplattform/README.md

Security Awareness Learning Platform

A containerized web application for security awareness training with modular, expandable lessons. Participants join events using pseudonyms and complete interactive security lessons including phishing detection, SQL injection demos, and more.

Features

• Hub-Based Architecture: Participants join events with pseudonyms (no registration required)
• Interactive Lessons: Phishing demos, SQL injection sandboxes, fake login forms, and more
• Modular Lesson System: Easy to expand by adding YAML configs and JavaScript modules
• Weighted Scoring: Configurable points and weights per lesson
• Admin Panel: Complete event and lesson management, participant data viewing
• Container-Based: Easy deployment with Docker Compose

Technology Stack

• Backend: Node.js + Express
• Frontend: React + Vite
• Database: PostgreSQL 15
• Containerization: Docker + Docker Compose
• Lesson Storage: YAML/JSON configurations + JavaScript modules

Quick Start

Prerequisites

• Docker and Docker Compose installed
• Git (optional, for version control)

Setup Instructions

1. Clone or download the project

   cd lernplattform
   

2. Configure environment variables

   cp .env.example .env
   

   Edit .env and set secure values for:

   • DB_PASSWORD - Database password
   • JWT_SECRET - JWT secret key (min 32 characters)
   • SESSION_SECRET - Session secret (min 32 characters)
   • ADMIN_DEFAULT_PASSWORD - Admin login password

3. Start the application

   docker-compose up -d
   

4. Wait for services to be healthy

   docker-compose ps
   

   All services should show "healthy" status.

5. Access the application

   • Frontend: http://localhost (port 80)
   • Backend API: http://localhost:3000
   • Health check: http://localhost:3000/health

Default Credentials

• Admin Login:
  • Username: admin
  • Password: Value set in .env (ADMIN_DEFAULT_PASSWORD)

Project Structure

lernplattform/
├── database/
│   └── init/
│       └── 01-schema.sql          # Database schema
├── backend/
│   ├── src/
│   │   ├── config/                # Configuration files
│   │   ├── middleware/            # Express middleware
│   │   ├── routes/                # API routes
│   │   ├── controllers/           # Route controllers
│   │   ├── services/              # Business logic
│   │   └── models/                # Database queries
│   ├── lessons/
│   │   ├── configs/               # Lesson YAML configs
│   │   └── modules/               # Lesson JavaScript modules
│   ├── Dockerfile
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── pages/                 # Page components
│   │   ├── components/            # Reusable components
│   │   ├── services/              # API services
│   │   └── styles/                # CSS styles
│   ├── Dockerfile
│   ├── nginx.conf
│   └── package.json
├── docker-compose.yml
└── .env.example

Development

Running in Development Mode

Backend Development

cd backend
npm install
npm run dev

The backend will run on port 3000 with hot reload.

Frontend Development

cd frontend
npm install
npm run dev

The frontend will run on port 5173 with hot reload.

Database Access

Connect to the PostgreSQL database:

docker-compose exec database psql -U lernplattform_user -d lernplattform

Viewing Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f database

Adding New Lessons

Lessons are modular and easy to add. Each lesson consists of:

1. A YAML configuration file (backend/lessons/configs/*.yaml)
2. A JavaScript module (backend/lessons/modules/*/index.js)

Step-by-Step Guide

1. Create YAML configuration in backend/lessons/configs/:

lessonKey: "my-new-lesson"
title: "My New Lesson"
description: "Learn about security concept X"
difficultyLevel: "beginner"
estimatedDuration: 15
module: "my-new-lesson"

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

  - id: "question-1"
    type: "question"
    questionType: "single_choice"
    question: "What is the answer?"
    options:
      - id: "option-1"
        text: "Correct answer"
        isCorrect: true
        points: 50
      - id: "option-2"
        text: "Wrong answer"
        isCorrect: false
        points: 0
    maxPoints: 50
    feedback:
      correct: "Great job!"
      incorrect: "Try again..."

scoring:
  passingScore: 70
  maxTotalPoints: 100

2. Create JavaScript module in backend/lessons/modules/my-new-lesson/:

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

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

  // Override methods if custom validation needed
  // Otherwise, base class handles standard question types
}

module.exports = MyNewLesson;

3. Add lesson to database (via admin panel or SQL):

INSERT INTO lessons (lesson_key, title, description, module_path, config_path, difficulty_level, estimated_duration)
VALUES ('my-new-lesson', 'My New Lesson', 'Description', 'my-new-lesson', 'my-new-lesson.yaml', 'beginner', 15);

4. Assign lesson to event via admin panel.

API Documentation

Participant Endpoints

• POST /api/participant/join - Join event with pseudonym
• GET /api/participant/events - List active events
• GET /api/participant/event/:eventId/lessons - Get lessons for event
• GET /api/participant/lesson/:lessonId - Get lesson content
• POST /api/participant/lesson/:lessonId/answer - Submit answer
• GET /api/participant/progress - Get progress

Admin Endpoints

• POST /api/admin/login - Admin authentication
• GET /api/admin/events - List all events
• POST /api/admin/events - Create new event
• PUT /api/admin/events/:eventId - Update event
• DELETE /api/admin/events/:eventId - Delete event
• POST /api/admin/events/:eventId/lessons - Assign lesson to event
• GET /api/admin/events/:eventId/participants - View participant data

Security Considerations

• All passwords are hashed with bcrypt
• JWT tokens for admin authentication
• Session tokens for participant authentication
• Parameterized SQL queries to prevent SQL injection
• CORS configured for security
• Security headers via Helmet.js
• Input validation on all endpoints
• Non-root user in Docker containers

Troubleshooting

Database Connection Issues

# Check database status
docker-compose ps database

# View database logs
docker-compose logs database

# Restart database
docker-compose restart database

Backend Not Starting

# Check backend logs
docker-compose logs backend

# Verify environment variables
docker-compose exec backend env | grep DB_

# Restart backend
docker-compose restart backend

Frontend Not Loading

# Check frontend logs
docker-compose logs frontend

# Verify nginx configuration
docker-compose exec frontend nginx -t

# Restart frontend
docker-compose restart frontend

Reset Everything

# Stop all services
docker-compose down

# Remove volumes (WARNING: Deletes all data!)
docker-compose down -v

# Rebuild and start
docker-compose up --build -d

License

ISC

Support

For issues and questions, please open an issue in the project repository.