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
-
Clone the repository:
git clone https://github.com/HenryJobst/resulter.git
-
Create and edit environment file
cp .env.example .env
-
Switch to the backend directory and start the SpringBoot server:
cd backend
./mvnw spring-boot:run
-
Switch to the frontend directory and start the Vue.js frontend:
cd frontend
npm install
npm run serve
-
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:
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
-
Klonen Sie das Repository:
git clone https://github.com/HenryJobst/resulter.git
-
Environment-Datei anlegen und anpassen
cp .env.example .env
-
Wechseln Sie in das Backend-Verzeichnis und starten Sie den SpringBoot-Server:
cd backend
./mvnw spring-boot:run
-
Wechseln Sie in das Frontend-Verzeichnis und starten Sie das Vue.js-Frontend:
cd frontend
npm install
npm run serve
-
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:
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.
