Merge/57 with 32 user persistence

.agent/workflows/git.md

@@ -0,0 +1,11 @@
+---
+description: Automated Git workflow to analyze message patterns, format code, stage, commit, and push changes.
+---
+
+// turbo-all
+1. Run `git status` to identify current changes and untracked files.
+2. Run `git log -n 15 --pretty=format:"%s"` to analyze the recent commit message style, prefixes, and patterns used in the repository.
+3. Apply code formatting in the backend by running `./gradlew spotlessApply` in the `backend` directory.
+4. Stage all changes in the repository using `git add .`.
+5. Based on the analysis in step 2 and the changes identified in step 1, generate a commit message that follows the project's style and run `git commit -m "<commit_message>"`.
+6. Push the committed changes to the current branch using `git push`.

.github/workflows/test_and_build.yml

@@ -1,58 +1,78 @@
-# This workflow will build a Java project with Gradle and cache/restore any dependencies to improve the workflow execution time
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-gradle
-
-name: Java CI with Gradle
+name: PR CI Pipeline
 
 on:
   push:
     branches:
       - "development"
+      - "main"
   pull_request:
-    branches: [ "development" ]
+    branches:
+      - "development"
+      - "main"
+      - "merge/**"
+      - "feature/**"
+
+permissions:
+  contents: read
+  pull-requests: read
 
 jobs:
   test:
+    name: test
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
       - name: Set up JDK 21
-        uses: actions/setup-java@v4.7.1
+        uses: actions/setup-java@v4
         with:
           java-version: '21'
           distribution: 'temurin'
+
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4.4.2
-      - name: Run tests
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Check Code Formatting (Spotless)
+        if: github.event_name == 'pull_request'
+        run: |
+          cd backend
+          ./gradlew spotlessCheck || {
+            echo "❌ Code formatting check failed!"
+            echo ""
+            echo "Please run the following command locally to fix formatting:"
+            echo "  cd backend && ./gradlew spotlessApply"
+            echo ""
+            echo "Then commit and push the changes."
+            exit 1
+          }
+
+      - name: Run Checkstyle
+        run: cd backend && ./gradlew checkstyleMain checkstyleTest
+
+      - name: Run Tests
         run: cd backend && ./gradlew :test
 
   build:
+    name: build
     needs: test
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
       - name: Set up JDK 21
-        uses: actions/setup-java@v4.7.1
+        uses: actions/setup-java@v4
         with:
           java-version: '21'
           distribution: 'temurin'
 
       - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4.4.2
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: gradle/actions/setup-gradle@v4
 
-      - name: Build with Gradle Wrapper
+      - name: Build with Gradle
         run: cd backend && ./gradlew :bootJar
-
-      # - name: Upload built jar
-      #   uses: actions/upload-artifact@v4
-      #   with:
-      #     name: Application
-      #     path: backend/build/libs/*.jar

README.md

@@ -10,59 +10,115 @@ This repository contains the source code for the Quantum Kit (QuaK) Web IDE.
 
 ## Docker Workflows
 
-### Development Workflow (Recommended)
-This is the **preferred way** to develop locally. It ensures a consistent environment and supports hot-reloading.
+### Development Workflow (Docker-only)
 
+This ensures a consistent environment and supports hot-reloading.
+
+1. **Start Backend & Database:**
+    * **Linux/macOS:**
 
-1.  **Start Backend & Database:**
-    *   **Linux/macOS:**
         ```bash
-        sudo docker-compose -f docker-compose.dev.yaml up --build
+        docker compose -f docker-compose.dev.yaml up --build
         ```
-    *   **Windows:**
+
+    * **Windows:**
+
         ```powershell
         docker-compose -f docker-compose.dev.yaml up --build
         ```
-    *   Runs the Spring Boot backend on port `8080`.
-    *   Runs MariaDB on port `3306`.
-    *   *Note:* The backend does **not** serve frontend files in this mode.
 
-2.  **Start Frontend:**
+    * Runs the Spring Boot backend on port `8080`.
+    * Runs MariaDB on port `3306`.
+    * *Note:* The backend does **not** serve frontend files in this mode.
+
+2. **Start Frontend:**
     In a new terminal:
+
     ```bash
     cd frontend
     npm run dev
     ```
-    *   Runs the Vite dev server on port `5173`.
-    *   Proxies API requests to `localhost:8080`.
-    *   Access the app at `http://localhost:5173`.
+
+### Hybrid Workflow (Debugger-Friendly)
+
+**Recommended for backend development.** This allows you to run the backend in your IDE or via terminal with a debugger while using Docker for the database.
+
+1. **Start Database:**
+
+    ```bash
+    docker-compose -f docker-compose.dev.yaml up -d database
+    ```
+
+2. **Start Backend (with Debugging):**
+    You can run the backend in debug mode via terminal. It will listen on port **5005** for a debugger while the API remains on **8080**.
+
+    ```bash
+    cd backend
+    ./gradlew bootRun -PjvmArgs="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"
+    ```
+
+    * **Port 8080:** Standard Web/API (Frontend stays connected).
+    * **Port 5005:** Debugging (Connect your IDE here via "Remote JVM Debug").
+
+3. **Start Frontend:**
+
+    ```bash
+    cd frontend
+    npm run dev
+    ```
+
+Access the app at `http://localhost:5173`.
 
 ### Production Workflow
+
 To run the full application (Backend + Frontend served statically):
 
-1.  **Start Application:**
+1. **Start Application:**
+
     ```bash
-    sudo docker-compose -f docker-compose.prod.yaml up --build
+    docker compose -f docker-compose.prod.yaml up --build
     ```
-    *   Builds the frontend and serves it via the backend (or Nginx if configured).
-    *   Runs the Spring Boot backend and MariaDB.
-    *   Access the app at `http://localhost:8080` (or the configured production port).
+
+    * Builds the frontend and serves it via the backend (or Nginx if configured).
+    * Runs the Spring Boot backend and MariaDB.
+    * Access the app at `http://localhost:8080` (or the configured production port).
 
 ## Developing
 
 Please have a look at the [developer guidelines](/docs/DEVELOPMENT.md).
 
+## Testing
+
+### Backend Tests
+
+To run the backend tests, execute the following command in the `backend` directory:
+
+```bash
+./gradlew test
+```
+
+### Frontend Tests
+
+To run the frontend tests, execute the following command in the `frontend` directory:
+
+```bash
+npm run test
+```
+
 ## Deployment
 
-The project will automatically be deployed when a change to the _development_-branch happens.
+The project will automatically be deployed when a change to the *development*-branch happens.
 
 ### Setting up the Deployment Server
+
 On a server of your choice, set up the following:
+
 * [Docker](https://docs.docker.com/engine/install/)
 * [Dokku](https://dokku.com/docs/getting-started/installation/)
   * Make sure to enable `vhost` during the installation-dialog (this is the default)
 
 Then, run the following commands:
+
 ```bash
 dokku apps:create quak
 dokku builder:set quak build-dir backend
@@ -74,25 +130,31 @@ cat github
 # Save the content of the private for later
 # You may also want to move the ssh-keys somewhere else
 ```
+
 We now want to set the GitHub-Secrets inside this repository:
-* _DEPLOYMENT_SERVER_ADDRESS_
-* _DEPLOYMENT_SERVER_SSH_KEY_
+
+* *DEPLOYMENT_SERVER_ADDRESS*
+* *DEPLOYMENT_SERVER_SSH_KEY*
   * This has the content of the private-key generated above
 
 Lastly, make sure that all relevant ports (e.g. 8080) are exposed to the outside world.
 
 ## Legacy Execution (Not Recommended)
+
 *Note: This method is deprecated. Please use the Docker Development Workflow above.*
 
 To run the QuaK editor manually without Docker, run:
 `gradlew bootRun`
 inside the `backend` directory
 
 ### Dependencies
+
 The project requires the following dependencies to be installed on the system:
+
 * Java >= Version 21
 
 ### Automatic installation of nodejs
+
 Through the use of the [gradle-node-plugin], the project can automatically install `npm`.
 If you want to use this feature, run any gradle-command with the flag `-PdownloadNode` (i.e. `gradlew :bootRun -PdownloadNode`).
 

backend/.dockerignore

@@ -0,0 +1,31 @@
+# Build artifacts
+build/
+.gradle/
+bin/
+/out/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.ipr
+*.iws
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Git
+.git/
+.gitignore
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node (in case backend references frontend)
+node_modules/

backend/README.md

@@ -1,5 +1,34 @@
 # QuaK Backend
 
+## Code Formatting and Style
+
+This project uses **Spotless** for code formatting and **Checkstyle** for style enforcement.
+
+### Commands
+
+| Command                              | Description                                    |
+|:-------------------------------------|:-----------------------------------------------|
+| `./gradlew spotlessApply`            | Auto-format all Java code                      |
+| `./gradlew spotlessCheck`            | Check if code is properly formatted            |
+| `./gradlew checkstyleMain checkstyleTest` | Run Checkstyle on all code            |
+
+### Before Creating a Pull Request
+
+**Spotless formatting checks only run on pull requests** (not on regular pushes to your branch).
+
+Before creating a PR, ensure your code is properly formatted:
+
+```bash
+cd backend
+./gradlew spotlessApply
+./gradlew spotlessCheck
+./gradlew checkstyleMain checkstyleTest
+```
+
+If the PR pipeline fails due to formatting, run `./gradlew spotlessApply` locally, commit, and push again.
+
+---
+
 ## Testing Workflows
 
 ### 1. Test-Kategorien