Flight Spotlight Rebuild Handoff (Java + Vaadin)

[petermunachi]

This doc is for onboarding a new intern to the OpenUTM stack and guiding the
rebuild of Flight Spotlight using Java + Vaadin. It includes local run
instructions for the current system and a clear task breakdown.

1) Context: OpenUTM

OpenUTM (https://openutm.net/) is an open-source UTM/U-Space stack. In this
org, the stack is split into:

• flight-passport: OAuth2/OIDC server that issues JWTs.
• flight_blender: UTM backend for flight data, declarations, geo-fences,
  remote ID, etc.
• flight-spotlight: The web UI that visualizes flight traffic and manages
  flight declarations.

2) Repositories (dev branches)

• https://github.com/SkyTradeLinks/flight-spotlight/tree/dev
• https://github.com/SkyTradeLinks/flight_blender/tree/dev
• https://github.com/SkyTradeLinks/flight-passport/tree/dev

3) System Overview (current implementation)

Flight Spotlight (Node/Express + EJS + Socket.IO) depends on:

• Flight Passport for login (OIDC) and service tokens (client credentials).
• Flight Blender for API data (flight declarations, approvals, ping, etc.).
• Redis for caching and Bull queues.
• Tile38 for geospatial indexes and in-memory flight positions.

Spotlight routes and views are in:

• flight-spotlight/routes/spotlight_noticeboard.js
• flight-spotlight/routes/launchpad.js
• flight-spotlight/views/* (EJS templates)

Realtime updates are sent via Socket.IO from flight-spotlight/util/io.js and
queue workers under flight-spotlight/queues/.

4) Local Run (recommended: Docker)

Prereqs (PC):

• Docker Desktop
• Git

4.1 Create the shared Docker network

docker network create interop_ecosystem_network

4.2 Flight Passport

git clone https://github.com/SkyTradeLinks/flight-passport.git
cd flight-passport
git checkout dev
cp env.template .env

Edit .env:

• JWT_ISSUER_DOMAIN=http://flight-passport:9000
• ENABLE_DEBUG=1
• SHOW_ADMIN=1
• Set DJANGO_SUPERUSER_* to your local credentials

Run:

docker compose up --build

Open:

• http://localhost:9000/
• http://localhost:9000/admin

4.3 Flight Blender

git clone https://github.com/SkyTradeLinks/flight_blender.git
cd flight_blender
git checkout dev
cp env.template .env

Edit .env (keep defaults unless you need to override):

• PASSPORT_URL=http://flight-passport:9000
• PASSPORT_JWKS_URL=http://flight-passport:9000/.well-known/jwks.json
• ALLOWED_HOSTS=localhost,127.0.0.1,host.docker.internal,flight-blender

Run:

docker compose -f docker-compose-dev.yml up --build

Verify:

• http://localhost:8000/ping

4.4 Flight Spotlight

git clone https://github.com/SkyTradeLinks/flight-spotlight.git
cd flight-spotlight
git checkout dev
cp env.template .env

Update .env for Docker:

• PASSPORT_URL=http://flight-passport:9000
• OIDC_DOMAIN=http://flight-passport:9000/o
• BLENDER_BASE_URL=http://flight-blender:8000
• SPOTLIGHT_BASE_URL=http://localhost:5000
• TILE38_SERVER=tile38
• TILE38_PORT=9851
• REDIS_URL=redis://redis-spotlight:6379
• Set MAPBOX_KEY
• Set CLIENT_ID / CLIENT_SECRET (see section 4.5)
• Set PASSPORT_BLENDER_CLIENT_ID / PASSPORT_BLENDER_CLIENT_SECRET (see 4.5)

Run:

docker compose up --build

Open:

• http://localhost:5000

4.5 Create OAuth clients in Passport

In Passport admin (/admin) create two applications:

1. Spotlight OIDC (Authorization Code)

• Redirect URI: http://localhost:5000/callback
• Save CLIENT_ID and CLIENT_SECRET

2. Blender Service (Client Credentials)

• Scopes: flightblender.read flightblender.write
• Audience: testflight.flightblender.com
• Save PASSPORT_BLENDER_CLIENT_ID and PASSPORT_BLENDER_CLIENT_SECRET

5) Local Run (no Docker, optional)

Use this only if Docker is not available.

• Flight Passport / Blender: Python 3.13 + uv
• Flight Spotlight: Node 18+

Each repo has a README.md with detailed local instructions.

6) Rebuild Task: Java + Vaadin

Goal: Replace the Node/Express Spotlight app with a Java + Vaadin app that
preserves functionality and integrations.

6.1 Must-Have Features

• OIDC login via Flight Passport.
• Noticeboard (text) view for flight declarations.
• Noticeboard (map/globe) view for flight declarations.
• Spotlight (live map) for traffic in an AOI (area of interest).
• Launchpad flow:
  • submit a flight declaration (GeoJSON + metadata)
  • view submission status
  • view operation status

6.2 Integrations to Preserve

From the current Node routes:

• Blender APIs used:

  • GET /flight_declaration_ops/flight_declaration?start_date=&end_date=&page=
  • GET /flight_declaration_ops/flight_declaration/<uuid>
  • POST /flight_declaration_ops/set_flight_declaration
  • PUT /flight_declaration_ops/flight_declaration_review/<uuid>
  • PUT /flight_declaration_ops/flight_declaration_state/<uuid>
  • GET /ping

• Passport usage:

  • OIDC login (authorization code)
  • Client credentials token for Blender API calls

• Redis + Tile38:

  • Tile38 stores real-time positions (set_air_traffic flow)
  • Redis stores metadata and queue state
  • Bull queues trigger polling of Blender, ADS-B feed, DSS subscriptions,
    and geo-fence fetches

6.3 Suggested Approach

• Implement a Java service (Spring Boot preferred) that:
  • Handles OIDC login with Passport
  • Retrieves a Passport token (client credentials) for backend calls to Blender
  • Provides a Vaadin UI that mirrors existing views
  • Implements or replaces the queue/worker logic used for live updates

6.4 Files to Review for Behavior

• flight-spotlight/views/* for current UI structure
• flight-spotlight/routes/spotlight_noticeboard.js
• flight-spotlight/routes/launchpad.js
• flight-spotlight/queues/*
• flight-spotlight/util/io.js

7) Deliverables

• A new Java + Vaadin app that:
  • Runs locally with clear setup steps
  • Connects to Passport + Blender + Redis + Tile38
  • Replaces current Spotlight functionality
• Updated documentation for setup and environment variables

8) Common Gotchas

• Passport JWT_ISSUER_DOMAIN controls allowed hosts.
  • For local: set JWT_ISSUER_DOMAIN=http://localhost:9000
• Blender auth expects Passport JWKS and audience settings.
• Ensure services share the interop_ecosystem_network when using Docker.