Skip to content

README.md

Latest commit

 

History

History
152 lines (106 loc) · 7.16 KB

README.md

File metadata and controls

152 lines (106 loc) · 7.16 KB

LEARN-Hub

A recommendation system prototype for Computer Science education activities that leverages automated content processing and category-based scoring algorithms to support teachers in activity selection and lesson planning.

This system was developed as part of a Master's thesis at the Technical University of Munich, Chair of Applied Education Technologies. The architecture prioritises transparency and explainability, enabling teachers to understand how recommendations are generated rather than relying on opaque black-box algorithms.

Overview

LEARN-Hub addresses the challenge of finding appropriate educational activities for computer science courses by implementing an intelligent recommendation engine. The system processes educational activity documents, analyses their pedagogical characteristics, and generates personalised recommendations based on teacher requirements such as target age group, available resources, and learning objectives aligned with Bloom's Taxonomy.

The recommendation engine implements content-based filtering with category-based scoring, offering an explainable alternative to collaborative filtering approaches. Teachers receive detailed scoring breakdowns across age appropriateness, topic relevance, duration fit, Bloom alignment, and series cohesion, fostering agency and trust in the recommendation process.

Architectural Overview

The system implements a three-tier containerised web application architecture following the System Design Document approach:

Client Subsystem: A React single-page application provides an interactive user interface for teachers and administrators. The client implements role-based access control, supports both light and dark themes, and maintains session-based authentication using sessionStorage for enhanced security on shared school computers.

Server Subsystem: A Spring Boot REST API server orchestrates the core application logic through specialised internal systems. The Recommendation System encapsulates the algorithmic intelligence. The User System manages identity through user, history, and favourites services. The Document System oversees content ingestion via PDF processing and LLM-assisted metadata extraction using Spring AI.

Data Layer: PostgreSQL serves as the primary data store, managing activities, user accounts, search history, and favourites. The database schema supports complex relationships between activities, topics, and user preferences whilst maintaining referential integrity.

Containerisation: Docker Compose orchestrates three containerised services on a single host, connected via an internal bridge network. The deployment includes health checks and dependency chains to ensure proper sequencing during startup.

Design Goals

The architecture addresses several key quality attributes:

  • Transparency (QA3): Category-based scoring with detailed breakdowns enables teachers to understand recommendations
  • Maintainability (QA7): Clear, explicit code with dependency injection favours clarity over convenience
  • Performance (QA5, QA6): Two-stage scoring pipeline and hard filtering ensure sub-three-second response times
  • Extensibility (QA1, QA8): Comprehensive OpenAPI documentation enables integration with external learning platforms

Architecture Diagrams

The docs/figures/ directory contains UML diagrams documenting the system architecture:

Subsystem Decomposition

Quick Start

See docs/dev-setup.md for the full development setup guide.

Quick start:

# Start PostgreSQL
docker compose -f docker/compose.yml up postgres -d

# Run migrations
make db-migrate

# Start server and client
make dev

Services

Once running, access the system at:

Environment Configuration

The application requires environment variables for API integrations, security keys, and database configuration:

cp example.env .env

Key configuration variables:

  • LLM_API_KEY - API key for automated content processing
  • JWT_SECRET_KEY - JWT token signing
  • POSTGRES_DB_URI - PostgreSQL JDBC connection string
  • EMAIL_* - Email service configuration for teacher verification

See example.env for a complete list of configurable variables.

Documentation

User Documentation: https://ls1intum.github.io/LEARN-Hub/

Developer Documentation is organised in the docs/ directory by architectural layer:

Local Development

Core System

Server

Client

Technology Stack

Server:

  • Java 21 with Spring Boot 3.4.1
  • Spring Data JPA with Hibernate ORM
  • Flyway for database migrations
  • PostgreSQL 17+ for relational data persistence
  • Spring AI with Ollama for LLM integration
  • Spring Security with JWT authentication
  • Maven for dependency management

Client:

  • React 19 with TypeScript for type safety
  • Vite for rapid build tooling with hot module replacement
  • Tailwind CSS for utility-first styling
  • shadcn/ui for accessible interface elements
  • Nginx for production serving and API proxying

Infrastructure:

  • Docker for containerisation with multi-stage builds
  • Docker Compose for container orchestration
  • GitHub Container Registry for image distribution

Development Tools:

  • Maven for Java dependency management
  • JUnit for server testing
  • Vitest for client testing

Development Commands

Server

cd server/
make dev          # Start development server
make test         # Run tests
make build        # Build the application
make db-migrate   # Run Flyway migrations

Client

cd client/
npm run dev       # Start development server
npm run test:run  # Run tests
npm run build     # Build for production
npm run lint      # Check code quality