URBREATH Proxy Manager

This Spring Boot server acts as a Proxy Manager for the URBREATH analysis engines. It implements a subset of the OGC API - Processes standard to bridge communications between front-end clients and the internal processing units.

---

Overview

The Proxy Manager handles authentication, job tracking, metadata enrichment, and the publication of analysis results to the URBREATH Catalog (IDRA) and long-term storage in MinIO (if the results aren't published on MinIO).

Currently, the system is focused on:

• Water Infiltration Analysis (supporting both preset and custom modes) for the cities of Leuven and Cluj-Napoca.
• NVE Analysis (supports air-filtration analysis)
• 3-30-300 Analysis (supports automatic publishing to MinIO via the middleware )
• Energy Label Analysis
• 15-minutes-city

---

Features

• OGC API Compliance: Implements standard endpoints for process discovery and job execution.
• Job Persistence: Extended storage of execution history via JobRecords, including support for re-executing dismissed jobs (rerun).
• Metadata Enrichment: Includes trackingData and externalTool identifiers in job executions.
• Security: JWT-based authentication and CORS management.
• Dynamic Template Engine: Centralized management of dataset and distribution templates, allowing flexible output definitions without code changes.
• Automated Job Retention: Automatic management of the job lifecycle via configurable retention policies, to ensure optimisation of MongoDB storage and compliance with retention periods for SUCCESSFUL, FAILED or DISMISSED jobs.
• Automated Storage Cleanup: Integrated recursive cleanup of associated files and directories from MinIO during job record deletion, preventing orphaned objects.
• Process UI Rendering: Provides ready-to-embed HTML forms for process execution via dynamic OGC HTML translation, with automatic cache invalidation on process updates.

---

API Documentation & Swagger

The server provides interactive documentation to explore and test the endpoints:

• Swagger UI: https://proxy-manager-dev.urbreath.tech/swagger-ui.html
• OpenAPI Specification: https://proxy-manager-dev.urbreath.tech/v3/api-docs

For a detailed guide on endpoints and payload structures, refer to the proxy_api_doc_v0.3.md.

---

Configuration & Execution

Prerequisites

• Java 17+
• Maven 3.6+
• A running MongoDB instance (for JobRecords and Processes persistence)

Quick Start

1. Configure Environment: Update src/main/resources/application.properties with your specific settings (Server Port, MongoDB URI, Security configurations).
2. Build the Project:

   mvn clean install

3. Run the Server:

   mvn spring-boot:run

Default Port

The server starts by default on port 8080. This can be modified in application.properties.

Implementation Notes

• JobRecords: Each execution generates a JobRecord document. This document aggregates StatusInfo, Execute parameters, and Results, along with additional tracking fields (trackingData, externalTool, titleand description).
• Automated Retention Policy: The system runs a scheduled (cron-based) task to periodically clean up records.

  Job Status	Policy
  SUCCESSFUL	After $10$ days (excluding those published in the URBREATH Catalogue)
  FAILED	After $7$ days
  DISMISSED	After $20$ day
  These settings can be overridden using environment variables (e.g. RETENTION_POLICY_SUCCESSFUL_DAYS, RETENTION_POLICY_FAILED_DAYS, RETENTION_POLICY_DISMISSED_DAYS, RETENTION_POLICY_CRON).

License

• Kitsune - Copyright (C) 2026 [Engineering Ingegneria Informatica S.p.A.]
• Licensed under the GNU General Public License version 3 (GPLv3).