EnduranceTrio

Table of Contents

1. Introduction
2. Platform Features
   1. Core Functionality
   2. API Endpoints
   3. Swagger UI & API Documentation
3. Development
   1. Technology Stack
   2. API Key Management
   3. Database
   4. Installation
   5. Code & Naming Conventions
   6. Programmatic Version Management
4. Deployment
   1. Container Architecture
   2. Server Setup
   3. Reverse Proxy Setup
   4. SSL Certificate
5. License

Introduction

EnduranceTrio is a web platform and REST API for endurance sports data and resources.

The project is centered on triathlon and related multisport disciplines, with an initial focus on Portugal. Its main long-term objective is to build a structured and reliable dataset of Portuguese triathlon events, results, athletes, and related content, starting from the earliest years of the sport and expanding over time toward broader historical coverage and more current competition data.

The platform combines a public-facing web application with a programmatic REST API. It is built on a Java 21 and Spring Boot 4 foundation and is designed to support both archival use cases, such as preserving and organizing historical race information, and operational use cases, such as telemetry ingestion and route management for live event scenarios.

Development Team

EnduranceTrio is a personal project created and maintained by Ricardo do Canto.

Platform Features

The platform is developed as a public-facing endurance sports website backed by a structured data model and supported by a dedicated API surface for tracker-domain functionality.

Core Functionality

EnduranceTrio currently provides two complementary platform surfaces:

• Web Application: A browser-based interface for exploring endurance sports data and related resources. The primary product direction is a structured database of Portuguese triathlon and related multisport events, results, athletes, and connected content. Development begins with a strong historical foundation and progressively expands toward more recent competitions and more timely race data as the underlying data model and ingestion workflows mature.

• REST API: A secure and documented API surface that currently exposes the platform's tracker domain. It provides scalable support for IoT telemetry ingestion, retrieval of device telemetry history, and GeoJSON route management, enabling live tracking and route-oriented integrations for endurance sports use cases.

Together, these two interfaces support the broader platform goal: combining structured endurance sports data, historical preservation, analytical potential, and practical event technology in a single evolving system.

API Endpoints

The currently available API endpoints belong to the tracker domain and are summarized below.

Method	Endpoint	Description	Authentication
GET	/tracker/v1/devices	Get last known telemetry for all existing devices	API Key Required
POST	/tracker/v1/devices	Submit a device telemetry data point	API Key Required
GET	/tracker/v1/devices/{device}/telemetry	Get historical telemetry for a device (supports pagination)	API Key Required
GET	/tracker/v1/routes	Get all route configurations	API Key Required
POST	/tracker/v1/routes	Submit a route configuration	API Key Required
GET	/tracker/v1/routes/({id}	Find route configuration by id	API Key Required
GET	/tracker/v1/routes/({id}/metrics	Retrieves the GeoJSON definition for a specific route	API Key Required

For detailed request and response schemas, examples, and error handling, see:

• Tracker Domain

Swagger UI & API Documentation

The EnduranceTrio API provides interactive documentation through Swagger UI, with separate documentation groups for different environments. This graphical interface allows you to:

• Explore all available endpoints.
• View request/response models (e.g., DeviceTelemetryDTO).
• Test API calls directly from your browser.

Environment-Specific Access

The Swagger UI endpoint varies by environment and deployment configuration:

Environment	Default URL	Note
Local Development	http://localhost:8080/swagger-ui.html	Direct application access
Public	openapi subdomain	Configured via Apache proxy

Selecting the Correct Environment Group

When you access Swagger UI, you must select the appropriate documentation group for your environment:

1. Look for the dropdown menu in the top-right corner of the Swagger UI page (labeled with the current group name)
2. Choose the correct group based on your environment:
   • Tracker Domain (LOCAL) - For local development (uses paths with /api prefix)
   • Tracker Domain (PROD) - For production use (uses paths without /api prefix)

Important: When accessing Swagger UI through the openapi subdomain in production, the gateway strips the /api prefix from paths. The documentation reflects the client-facing URLs, not the internal application paths.

Why this matters:

• Different groups uses different server URLs and path structures
• Selecting the wrong group may show incorrect endpoint URLs
• The authentication setup is shared between groups

Authentication Guide

The EnduranceTrio API requires Dual-Header Authentication. To test protected endpoints in Swagger UI, follow these steps:

1. Click the Authorize button at the top right of the page.
2. You will see a modal with two separate sections. You must configure both to successfully make requests:

Field Label	Corresponding Header	Value Format	Action
Account Name	ET-Owner	Your account identifier (e.g., system)	Enter ID & click Authorize
API Key	Authorization	Bearer <your_api_key>	Enter Key & click Authorize

Important: You must click the Authorize button for each field independently. Ensure both padlocks appear "locked" (closed) before closing the modal and testing endpoints.

Development

For detailed development documentation (API key management, database configuration, installation instructions, coding conventions, etc.), please refer to the Development Guide.

Quick Start

1. Prerequisites: Java 21, Maven, PostgreSQL
2. Clone: git clone git@github.com:EnduranceCode/endurancetrio-community.git
3. Configure: Set up application-secrets.yaml from template
4. Build: ./mvnw clean install (frontend assets are generated automatically in production mode)
5. Run: Use ./launch-app.sh or the provided IntelliJ run configuration, which triggers the shared GenerateFrontendAssetsDev run configuration before startup so browser source maps are available

Frontend assets are generated into endurancetrio-app/target/generated-resources/frontend/static/.

• Maven package builds use the production Webpack mode: minified assets, no source maps, raster image optimization, and runtime assets packaged under BOOT-INF/classes/static/.
• EnduranceTrioApplication uses GenerateFrontendAssetsDev before startup so frontend debugging works out of the box.
• EnduranceTrioApplicationWithFrontendWatch starts both EnduranceTrioApplication and FrontendAssetsWatch for live frontend rebuilds.

See the full Development Guide for comprehensive instructions.

Tracker Domain Development Model

The Tracker functionality (IoT telemetry ingestion and GeoJSON route management) is developed in its own endurancetrio-tracker repository and incorporated into this project via git merge.

This dual-repo approach allows the Tracker to evolve independently while its code is periodically merged back into this repository. Issues discovered in Tracker-domain code during integration are filed in the tracker repository.

See docs/development.md for the full merge workflow and operational instructions.

Deployment

For deployment instructions (container architecture, server and reverse proxy setup, SSL certificate configuration, etc.), please refer to the Deployment Guide.

License

This project is licensed under the Functional Source License, Version 1.1, ALv2 Future License. See the LICENSE.md file for details.