# 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**
   ```bash
   cd lernplattform
   ```

2. **Configure environment variables**
   ```bash
   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**
   ```bash
   docker-compose up -d
   ```

4. **Wait for services to be healthy**
   ```bash
   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
```bash
cd backend
npm install
npm run dev
```

The backend will run on port 3000 with hot reload.

#### Frontend Development
```bash
cd frontend
npm install
npm run dev
```

The frontend will run on port 5173 with hot reload.

### Database Access

Connect to the PostgreSQL database:
```bash
docker-compose exec database psql -U lernplattform_user -d lernplattform
```

### Viewing Logs

```bash
# 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/`:

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

```javascript
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):

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

```bash
# Check database status
docker-compose ps database

# View database logs
docker-compose logs database

# Restart database
docker-compose restart database
```

### Backend Not Starting

```bash
# 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

```bash
# Check frontend logs
docker-compose logs frontend

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

# Restart frontend
docker-compose restart frontend
```

### Reset Everything

```bash
# 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.