Kitsune is the middleware integration layer developed within the URBREATH project. It acts as the backbone between front-end clients, OGC-compliant analysis engines, and long-term storage services.
The system is built on top of the OGC API - Processes standard and uses Apache Kafka as its internal message bus.
⚠️ No UI is currently available. All interactions are via API.
┌─────────────────────────────────────────────────────┐
│ LEGEND │
│ ───────► Constant Flow │
│ - - - -> Optional Flow │
└─────────────────────────────────────────────────────┘
┌───────────────┐ request ┌───────────────┐ produce ┌───────────────────────────────────────────────────┐
│ │ ───────────► │ │ ────────► │ APACHE KAFKA │
│ EXTERNAL TOOL │ │ PROXY │ └───────────┬──────────────┬──────────────┬─────────┘
│ │ ◄─────────── │ │ ◄──────── (consume) │ │ │
└───────────────┘ response │ │ │consume │consume │consume
└───────┬───────┘ │ │ │
write│read ▼ ▼ ▼
▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
┌───────┐ │ │ │ │ │ │
│ DB │ (produce) │ MIDDLEWARE │ │ MIDDLEWARE │ │ MIDDLEWARE │
└───────┘ ◄────────── │ 1 │ │ 2 │ │ n │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
┌ ─ ─ ─ ─ polling─ ─ ─ ─ ─ ─┘ │ │
│ request │polling │ │
▼ ▼ ▼ ▼
┌───────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ │ ◄─── write ── │ ANALYSIS │ │ ANALYSIS │ │ ANALYSIS │
│ OS │ ◄─── write ── │ SERVICE 1 │ │ SERVICE 2 │ │ SERVICE n │
│ │ ◄─── write ── └──────────────┘ └──────────────┘ └──────────────┘
└───────┘ sync/async response ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─►(MIDDLEWARE)
| Repository | Description |
|---|---|
| kitsune-proxy | Entry point. Implements OGC API - Processes and others internal APIs. Handles authentication (JWT), job lifecycle, metadata enrichment, and publication to catalog (IDRA) and MinIO. |
| kitsune-middleware-core | Shared library. Provides base engine classes (SingleCallAnalysisEngine, OrchestratedAnalysisEngine), Kafka lifecycle management, OGC validation, and MinIO integration. |
| kitsune-middleware-water-infiltration | Middleware for Water Infiltration analysis. Supports preset and custom modes with OGC-to-tool input translation and spatial geometry normalization. |
| kitsune-middleware-nature-value-explorer | Middleware for Air Filtration analysis. |
| kitsune-middleware-3-30-300 | Middleware for 3-30-300 analysis. Orchestrates parallel calls to VITO services and persists raster (GeoTIFF) outputs to MinIO. |
| kitsune-middleware-ldt-toolbox-energy-label | Middleware for building energy efficiency classification. Handles spatial area calculation (JTS). |
| kitsune-middleware-15-minutes | Middleware for 15-Minutes City urban accessibility analysis. |
| kitsune-storage-lib | Shared MinIO storage library. Provides standardized upload, path generation, and recursive directory cleanup. |
| Layer | Technology |
|---|---|
| Runtime | Java 17, Spring Boot |
| Messaging | Apache Kafka |
| Storage | MinIO (S3-compatible) |
| Database | MongoDB |
| API Standard | OGC API - Processes |
| Security | JWT |
Each component is independently deployable. Refer to the individual repository README for setup instructions.
The general dependency order for local deployment is:
kitsune-storage-lib → kitsune-middleware-core → [middlewares] → kitsune-proxy
The Proxy exposes interactive API documentation:
- Swagger UI:
https://proxy-manager-dev.urbreath.tech/swagger-ui.html - OpenAPI Spec:
https://proxy-manager-dev.urbreath.tech/v3/api-docs
Kitsune — Copyright (C) 2026 [Engineering Ingegneria Informatica S.p.A.]
Licensed under the GNU General Public License v3.0 (GPLv3).
See LICENSE for details.