frag.jetzt

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 23 Open GitHub ↗

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.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Quality Gate Status](https://sonar.arsnova.eu/api/project_badges/measure?project=frag.jetzt-frontend&metric=alert_status&token=sqb_b08ddcd80ffd5373cec06b06190b2090a3808b0f)](https://sonar.arsnova.eu/dashboard?id=frag.jetzt-frontend)
[![Technical Debt](https://sonar.arsnova.eu/api/project_badges/measure?project=frag.jetzt-frontend&metric=sqale_index&token=sqb_b08ddcd80ffd5373cec06b06190b2090a3808b0f)](https://sonar.arsnova.eu/dashboard?id=frag.jetzt-frontend)
[![Maintainability Rating](https://sonar.arsnova.eu/api/project_badges/measure?project=frag.jetzt-frontend&metric=sqale_rating&token=sqb_b08ddcd80ffd5373cec06b06190b2090a3808b0f)](https://sonar.arsnova.eu/dashboard?id=frag.jetzt-frontend)
[![Lines of Code](https://sonar.arsnova.eu/api/project_badges/measure?project=frag.jetzt-frontend&metric=ncloc&token=sqb_b08ddcd80ffd5373cec06b06190b2090a3808b0f)](https://sonar.arsnova.eu/dashboard?id=frag.jetzt-frontend)

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

![Screenshot of frag.jetzt](https://raw.githubusercontent.com/thm-projects/frag.jetzt/staging/src/assets/images/startpage.webp "The frag.jetzt application in action")

## 📚 Table of Contents

1. [👨‍🏫 Mentoring & Support](#mentoring--support)
1. [📝 Introduction](#introduction)
1. [⚙️ Core Functionalities](#core-functionalities)
1. [🏗️ Project Architecture](#project-architecture)
1. [💻 Setting Up the Development Environment](#setting-up-the-development-environment)
1. [🔍 Static Code Analysis of the Angular Frontend](#static-code-analysis-of-the-angular-frontend)
1. [💻 Understanding the Codebase](#understanding-the-codebase)
1. [🤝 Contribution and Collaboration Guidelines](#contribution-and-collaboration-guidelines)
1. [✅ Definition of Done Checklist](#definition-of-done-checklist-for-user-stories)
1. [📜 Project History](#project-history)
1. [📋 Project Documentation](#project-documentation)
1. [❓ Troubleshooting FAQ](#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](mailto:klaus.quibeldey@gmail.com)

- **Technical Mentoring and Chief Developer:**  
  Ruben Bimberg (M.Sc.) – [ruben.bimberg@mni.thm.de](mailto: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](https://gitlab.arsnova.eu/arsnova/frag.jetzt/-/issues).

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](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) or [NVM-windows](https://github.com/coreybutler/nvm-windows?tab=readme-ov-file#install-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:

```bash
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](https://staging.frag.jetzt) or [production](https://frag.jetzt).
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 <kbd>Ctrl + C</kbd>).

### Access frag.jetzt

If you did not change any ports, the application is now available under [localhost:4200](http://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](http://localhost:8025/).

## Static Code Analysis of the Angular Frontend

To ensure high-quality code and maintainability, we use [SonarQube](https://www.sonarsource.com/) for static code analysis of the Angular frontend:

[![Lines of Code](https://sonar.arsnova.eu/api/project_badges/measure?project=frag.jetzt-frontend&metric=ncloc&token=sqb_b08ddcd80ffd5373cec06b06190b2090a3808b0f)](https://sonar.arsnova.eu/dashboard?id=frag.jetzt-frontend)

---

**To run a local analysis, follow these steps:**

1. **Navigate to the analysis directory:**

```bash
   cd analysis
   ```

2. **Remove previously running containers and volumes:**

```bash
   sudo docker compose down -v
   ```

3. **Pull the latest images and update built images:**

```bash
   sudo docker compose pull
   sudo docker compose build
   ```

4. **Start the SonarQube server:**

```bash
   sudo docker compose up -d sonarqube
   ```

5. **Run the analysis:**

```bash
   sudo docker compose run --rm analysis
   ```

6. **Look at the results at [http://localhost:9000](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](https://material.angular.io/) 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](https://developer.chrome.com/docs/lighthouse/overview/), 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](https://www.deepl.com/translator).

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](https://sonar.arsnova.eu). Ensure technical debt has not significantly increased due to recent commits.

## Project History

### Vision Statement (version 2024)

<details>
<summary>
 AI-Enhanced Educational Interactions: Towards Next-Generation Learning
</summary>
 
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.

</details>

### Vision Statement (version 2023)

<details>
<summary>
 Dual-Mode Learning Platform: The Evolution of frag.jetzt from ARS to PLE
</summary>
 
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.
</details>

### Vision Statement (version 2022)

<details>
<summary>
 Pioneering Audience Engagement through Interactive and Gamified Learning
</summary>
 
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.
</details>

## Project Documentation

- Glossary: [PDF](https://git.thm.de/arsnova/frag.jetzt/-/raw/staging/docs/diagrams/Glossary.pdf)

- Use Case Diagram: [SVG](https://staging.frag.jetzt/assets/images/Use_Case_Diagram.svg)

- Domain Diagram: [SVG](https://staging.frag.jetzt/assets/images/Domain_Diagram.svg)

- Activity Diagram for Bonus Awarding: [SVG](https://staging.frag.jetzt/assets/images/activity_diagram_bonus_option.svg)

- Activity Diagram for Brainstorming: [SVG](https://staging.frag.jetzt/assets/images/activity_diagram_brainstorming.svg)

- frag.jetzt Backend: [Swagger](https://frag.jetzt/api/webjars/swagger-ui/index.html)

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

frag.jetzt

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README