Resulter

Overview

Resulter is an innovative web application for orienteering enthusiasts and organizers of orienteering competitions.

This application allows for the input of competition results files and subsequently displays detailed result lists. As the first major feature there is the possibility to design certificate templates and activate certificate download for an event for every single participant. Other functions include:

• Calculation and display of cup and ranking points for the German Nebel-Cup, Kristall-Cup and the North-East-Ranking
• Split time analysis with various evaluations (ranking, mental resilience, anomaly detection, hanging detection)

Possible future extensions: generalization of cups, calculation of recommended course lengths, etc.

Architecture

The frontend communicates with the backend via a REST API, which is implemented in the pattern of Hexagonal Architecture. Authentication follows the Backend-for-Frontend (BFF) pattern, where the backend handles OAuth2/OIDC communication with Keycloak, and the frontend uses secure session cookies.

Technologies

• Backend: Java, SpringBoot, Spring Data JDBC
• Frontend: Typescript, Vue.js 3, Vite, Pinia, Primevue, Tailwind, Tanstack Query
• Communication: REST API
• Authentication/Authorisation: BFF Pattern with Keycloak (OAuth2/OIDC), Session-based
• Database: PostgreSQL, H2

Prerequisites

• Java (recommended: latest version)
• Node.js and npm/pnpm
• An IDE of your choice (e.g., IntelliJ IDEA for backend, VSCode for frontend)

Installation

1. Clone the repository:

   git clone https://github.com/HenryJobst/resulter.git
   

2. Create and edit environment file

   cp .env.example .env
   

3. Switch to the backend directory and start the SpringBoot server:

   cd backend
   ./mvnw spring-boot:run
   

4. Switch to the frontend directory and start the Vue.js frontend:

   cd frontend
   npm install
   npm run serve
   

5. Deployment

   Two build approaches available:

   Option 1: Dockerfile-based build (default)

   • Separate build scripts for frontend and backend: ./backend/build.sh and ./frontend/build.sh
   • Traditional Docker build with Alpine base images

   Option 2: Paketo Buildpacks (Cloud Native Buildpacks)

   • Build scripts: ./backend/build-paketo.sh and ./frontend/build-paketo.sh
   • Requires pack CLI: brew install buildpacks/tap/pack (macOS) or see buildpacks.io
   • Benefits: 12-factor apps, runtime configuration, automatic SBOM generation, non-root user
   • CI/CD: .github/workflows/build-paketo.yml

   Running the application:

   • There is a compose file in deploy/resulter/ to start the complete application with database in Docker containers

Usage

After starting the application, you can upload result files from orienteering competitions. The application processes these and provides detailed result lists. Future features such as certificate printing and points calculations will be added in upcoming versions.

Documentation:

• Guide for integrating new fonts into document PDF export (iText): doc/itext-font-integration-guide-generic.md

Contributions

We welcome contributions to the development of Resulter. Please consult with us in advance to avoid duplicate developments.

License

Resulter © 2023-2026 by Henry Jobst is licensed under CC BY-NC-ND 4.0 - see LICENSE.txt for details.

---

Überblick

Resulter ist eine innovative Web-Anwendung für Orientierungslauf-Enthusiasten und Organisatoren von Orientierungslauf-Wettkämpfen.

Mit dieser Anwendung können Ergebnisdateien von Wettkämpfen eingelesen und anschließend detaillierte Ergebnislisten angezeigt werden. Als erste große Funktion besteht die Möglichkeit, Urkundenvorlagen zu gestalten und für eine Veranstaltung den Urkunden-Download für jeden einzelnen Teilnehmer zu aktivieren. Weitere Funktionen umfassen:

• Berechnung und Anzeige von Cup- und Ranglistenpunkten für den deutschen Nebel-Cup, Kristall-Cup und die Nord-Ost-Rangliste
• Splittzeiten-Analyse mit verschiedenen Auswertungen (Ranking, mentale Belastbarkeit, Anomalieerkennung, Hängererkennung)

Zukünftige mögliche Erweiterungen: Generalisierung von Cups, Berechnung von empfohlenen Bahnlängen etc.

Architektur

Das Frontend kommuniziert über eine REST-API mit dem Backend, welches im Muster der Hexagonalen Architektur implementiert ist. Die Authentifizierung folgt dem Backend-for-Frontend (BFF) Pattern, wobei das Backend die OAuth2/OIDC Kommunikation mit Keycloak übernimmt und das Frontend sichere Session-Cookies verwendet.

Technologien

• Backend: Java, SpringBoot, Spring Data JDBC
• Frontend: Typescript, Vue.js 3, Vite, Pinia, Primevue, Tailwind, Tanstack Query
• Kommunikation: REST API
• Authentifizierung/Berechtigung: BFF Pattern mit Keycloak (OAuth2/OIDC), Session-basiert
• Datenbank: PostgreSQL, H2

Voraussetzungen

• Java (empfohlen: neueste Version)
• Node.js und npm/pnpm
• Eine IDE Ihrer Wahl (z.B. IntelliJ IDEA für Backend, VSCode für Frontend)

Installation

1. Klonen Sie das Repository:

   git clone https://github.com/HenryJobst/resulter.git
   

2. Environment-Datei anlegen und anpassen

   cp .env.example .env
   

3. Wechseln Sie in das Backend-Verzeichnis und starten Sie den SpringBoot-Server:

   cd backend
   ./mvnw spring-boot:run
   

4. Wechseln Sie in das Frontend-Verzeichnis und starten Sie das Vue.js-Frontend:

   cd frontend
   npm install
   npm run serve
   

5. Deployment

   Zwei Build-Varianten verfügbar:

   Option 1: Dockerfile-basierter Build (Standard)

   • Separate Build-Skripte für Frontend und Backend: ./backend/build.sh und ./frontend/build.sh
   • Traditioneller Docker-Build mit Alpine-Base-Images

   Option 2: Paketo Buildpacks (Cloud Native Buildpacks)

   • Build-Skripte: ./backend/build-paketo.sh und ./frontend/build-paketo.sh
   • Benötigt pack CLI: brew install buildpacks/tap/pack (macOS) oder siehe buildpacks.io
   • Vorteile: 12-Faktor-Apps, Runtime-Konfiguration, automatische SBOM-Generierung, Non-Root-User
   • CI/CD: .github/workflows/build-paketo.yml

   Anwendung ausführen:

   • Im Verzeichnis deploy/resulter/ gibt es ein Docker-Compose-File, mit dem die komplette Anwendung mit Datenbank gestartet werden kann

Nutzung

Nach dem Starten der Anwendung können Sie Ergebnisdateien von Orientierungslauf-Wettkämpfen hochladen. Die Anwendung verarbeitet diese und stellt detaillierte Ergebnislisten zur Verfügung. Zukünftige Funktionen wie Urkundendruck und Punkteberechnungen werden in kommenden Versionen ergänzt.

Dokumentation:

• Anleitung zum Einbinden neuer Schriftarten in den Dokument-PDF-Export (iText): doc/itext-font-integration-guide-generic.md

Beiträge

Wir begrüßen Beiträge zur Weiterentwicklung von Resulter. Bitte halten Sie vorab Rücksprache, um Doppelentwicklungen zu vermeiden.

Lizenz

Das Projekt Resulter © 2023-2026 von Henry Jobst ist unter der Lizenz CC BY-NC-ND 4.0 lizenziert - siehe LICENSE.txt für Details.