Developer Onboarding Guide

Nomen est omen: The app's name, frag.jetzt (German for "ask.now"), says it all—highlighting both its main purpose and its web address, https://frag.jetzt.

📚 Table of Contents

1. 👨‍🏫 Mentoring & Support
2. 📝 Introduction
3. ⚙️ Core Functionalities
4. 🏗️ Project Architecture
5. 💻 Setting Up the Development Environment
6. 🔍 Static Code Analysis of the Angular Frontend
7. 💻 Understanding the Codebase
8. 🤝 Contribution and Collaboration Guidelines
9. ✅ Definition of Done Checklist
10. 📜 Project History
11. 📋 Project Documentation
12. ❓ Troubleshooting FAQ

🎉 Welcome to the frag.jetzt dev community!

Your contributions are invaluable to continuously improving our interactive educational tools. Let's innovate together! 🎉 🌍 👩‍💻

Mentoring & Support

We strongly believe in supporting new contributors through mentoring to facilitate an effective and welcoming onboarding experience.

• Project Mentoring and General Guidance:
  Prof. Dr. Klaus Quibeldey-Cirkel (Project Lead) – klaus.quibeldey@gmail.com

• Technical Mentoring and Chief Developer:
  Ruben Bimberg (M.Sc.) – ruben.bimberg@mni.thm.de

If you need assistance, have technical questions, or require general support, please open an issue on our GitLab issue tracker.

Do not hesitate to reach out—we're happy to help!

Introduction

frag.jetzt is an open-source Progressive Web Application (PWA) developed by Technische Hochschule Mittelhessen (THM) to facilitate interactive Q&A sessions and enhance audience engagement in educational settings. The platform supports collaborative educational interactions through moderated, real-time, multilingual dialogue and incorporates advanced AI-driven features. It adheres strictly to ethical frameworks and data protection standards, including GDPR compliance.

Core Functionalities

AI-Based Moderation

• Advanced moderation using AI and contextual pipelines, effectively managing inappropriate content.

Interactive Keyword Cloud

• Real-time thematic visualizations using NLP technologies for improved navigation and interaction.

Multilingual Support and Compliance

• Comprehensive multilingual functionality combined with stringent ethical and data protection compliance.

Retrieval-Augmented Generation (RAG)

• Enhances AI-generated content, providing accurate and contextually relevant interactions.

Project Architecture

frag.jetzt employs a modular architecture comprising:

• Frontend Layer: Developed using Angular and TypeScript, optimized as a Progressive Web Application (PWA) ensuring accessibility, cross-platform compatibility, and enhanced user experience.
• Backend Layer: Provides core functions such as managing Q&A sessions, moderating content, and supporting multilingual processing.
• AI Integration: Incorporates cutting-edge Natural Language Processing (NLP) technologies like GPT-based Large Language Models (LLMs), vector embeddings, and Retrieval-Augmented Generation (RAG), enhancing content moderation and user interactions.

Setting Up the Development Environment

Required Software

Before starting, ensure the following software components are installed:

• Node.js: Install Node.js, preferably managed via a version manager like NVM or NVM-windows when using windows.

• Operating System (only when using docker): Recommended to use GNU/Linux distributions.

  Note: Using Windows Subsystem for Linux 2 (WSL2) is possible but may have limitations, such as handling file events.

• Docker and Docker Compose: Only required, when the full infrastructure is needed for development.

macOS Specific Docker Instructions

If Docker credential errors arise (ERROR: failed to solve: error getting credentials - err: exit status 1), adjust your Docker configuration as follows:

nano ~/.docker/config.json

Change "credsStore": "desktop" to "credsStore": "osxkeychain".

frag.jetzt Development with Dependencies

frag.jetzt consists of a large number of backend services. To simplify the process, a startup script is available via npm run app.

When using docker, an admin account is available with email admin@admin and password admin.

If you only want to change something at the frontend or you dont have enough resources, you can run the app via staging or production. There is no admin account available and you must log in with a guest account. This process runs directly on your terminal, so you do not need to explicitly view the logs or terminate the process. You can simply cancel the process to end it (usually with Ctrl + C).

Access frag.jetzt

If you did not change any ports, the application is now available under localhost:4200.

When you started with docker, all emails from the system are intercepted and can be viewed in the Mailhog interface at localhost:8025.

Static Code Analysis of the Angular Frontend

To ensure high-quality code and maintainability, we use SonarQube for static code analysis of the Angular frontend:

---

To run a local analysis, follow these steps:

1. Navigate to the analysis directory:

   cd analysis

2. Remove previously running containers and volumes:

   sudo docker compose down -v

3. Pull the latest images and update built images:

   sudo docker compose pull
   sudo docker compose build

4. Start the SonarQube server:

   sudo docker compose up -d sonarqube

5. Run the analysis:

   sudo docker compose run --rm analysis

6. Look at the results at http://localhost:9000

Understanding the Codebase

Our codebase is organized into several key components that work together to deliver the frag.jetzt experience:

Frontend Architecture

• Core Module: Contains essential services, models, and utilities used throughout the application
• User Module: Handles authentication, user profiles, and session management
• Room Module: Manages the creation and configuration of Q&A sessions
• Question Module: Implements question creation, voting, and moderation features
• AI Module: Integrates NLP capabilities for content moderation and keyword extraction

Key Files and Entry Points

• app.module.ts: Main application module that bootstraps the application
• app-routing.module.ts: Defines the application's route structure
• environment.ts: Contains environment-specific configuration variables
• services/http.service.ts: Central service for handling API communications

Development Workflows

• Adding a New Feature: Start by creating a feature branch from staging, implement your changes, add tests, and submit a merge request
• Fixing a Bug: Identify the root cause using the browser console and server logs, create a fix branch, implement and test your solution
• Modifying UI Components: Follow our component structure using Angular Material and ensure responsive design across all device sizes

Contribution and Collaboration Guidelines

• Issue Tracking: Document bugs or feature requests clearly in GitLab.
• Branch Management: Branch from the staging branch for features and bug fixes.
• Commit Standards: Follow concise, descriptive commit messages in imperative mood and adhere to project style standards (ESLint, Prettier).
• Testing Protocol: Consistently write and run unit tests and end-to-end tests.

Definition of Done Checklist for User Stories

Ensure each completed User Story meets the following criteria:

1. Cross-browser Compatibility:
   The feature is tested against all acceptance criteria in Chrome, Firefox, and Safari.

2. Performance Analysis:
   The feature does not regress in any category of the Lighthouse Analysis, except possibly »Performance«.

3. Responsive Design:
   The feature is fully responsive on all screens, from small smartphones to large 4K displays.

4. Accessibility:
   The feature is accessible and fully usable on all supported devices and screen sizes.

5. Multilingual Support:
   The feature is available in all supported languages (English, French, and German). Translations must be completed using DeepL.

6. Tooltips:
   All icons and toggle buttons include descriptive tooltips.

7. Theme Compatibility:
   The feature maintains visual consistency and usability across all available themes.

8. Branch Integration:
   The feature branch has been successfully merged with the staging branch.

9. Merge Request:
   A merge request to the staging branch has been created and clearly documented.

10. Conflict Resolution:
    The merge request has no conflicts and merges cleanly into staging.

11. Peer Code Review:
    The code has been reviewed and approved by at least one developer external to the original development team.

12. Product Owner Approval:
    The product owner has been assigned and has reviewed the merge request.

13. Technical Debt Assessment:
    Code quality and technical debt have been assessed with SonarQube. Ensure technical debt has not significantly increased due to recent commits.

Project History

Vision Statement (version 2024)

AI-Enhanced Educational Interactions: Towards Next-Generation Learning

In 2024, we successfully built upon the robust foundation and widespread adoption of frag.jetzt as a premier interactive platform by leveraging cutting-edge AI technologies, including Retrieval-Augmented Generation (RAG) and advanced Large Language Models (LLMs). Our primary focus was integrating these technologies to transform frag.jetzt from a conventional interactive platform into a sophisticated intelligent assistant. We successfully facilitated deeply adaptive and individualized learning paths, significantly enhancing educational outcomes and accessibility on a global scale. Through these strategic innovations, frag.jetzt solidified its position at the forefront of intelligent educational technology.

Vision Statement (version 2023)

Dual-Mode Learning Platform: The Evolution of frag.jetzt from ARS to PLE

In 2023, we set forth an ambitious plan to evolve frag.jetzt from its roots as a reliable Audience Response System (ARS) into an AI-supported Personal Learning Environment (PLE). Our goal was to attract a broader user base by offering customizable learning environments and seamless transitions between educator and learner roles. This transition significantly enriched user engagement, expanded our audience, and established a dynamic and diverse educational ecosystem.

Vision Statement (version 2022)

Pioneering Audience Engagement through Interactive and Gamified Learning

In 2022, our goal with the innovative platform frag.jetzt was to lead the market of audience response systems specifically designed for educational environments. Our browser-based, GDPR-compliant Q&A platform leveraged gamified incentives, such as bonus points for quality questions, to foster interactive and anonymous participation. This unique approach significantly boosted classroom engagement, laying a strong foundation for future innovations and growth.

Project Documentation

• Glossary: PDF

• Use Case Diagram: SVG

• Domain Diagram: SVG

• Activity Diagram for Bonus Awarding: SVG

• Activity Diagram for Brainstorming: SVG

• frag.jetzt Backend: Swagger

Troubleshooting FAQ

Common Issues and Solutions

Issue	Possible Cause	Solution
Docker containers fail to start	Port conflicts with existing services	Check if ports 4200, 8080, or 27017 are already in use and stop those services
Frontend compilation errors	Outdated Node.js version	Ensure you're using the recommended Node.js version (see Requirements section)
Authentication fails in development	Email verification issues	Check Mailhog at localhost:8025 for verification emails
Changes not reflecting in browser	Browser caching	Hard refresh (Ctrl+F5) or clear browser cache
Database connection errors	PostgreSQL container not running	Run docker ps to check container status and restart if needed

Debugging Tips

• Check the browser console (F12) for frontend errors
• Review Docker logs with npm run docker and selecting option 4
• For backend issues, check the Spring Boot logs in the terminal
• Enable verbose logging by setting DEBUG=true in your environment variables