koala73 / koala73/worldmonitor

feat(military): named-entity watchlists (Plane-Alert / Yacht-Alert / PLAN-CCG) joined on hex + MMSI

Open
#6,228 0 comments 0 reactions 0 assignees View on GitHub
area: map area: military feature P2
Dominant language
TypeScript
Stars
86.6k
Forks
13.1k
Avg merge
8h 4m
Merged PRs (30d)
825

Description

## Summary

Add named-entity watchlists keyed on identifiers **we already ingest** — ICAO 24-bit hex for
aircraft, MMSI for vessels — so tracked aircraft and ships surface as *"Marine One"*,
*"Russian government Il-96"*, or *" superyacht"* instead of an anonymous contact.

This is the best value-per-effort item from the source audit: **no new upstream, no new API key,
no new quota, no new runtime failure mode.** It is a static join over data already flowing.

## What this is

`../shadowbroker` ships three bundled watchlists, all loaded from local JSON at import time —
no network dependency at runtime:

| Watchlist | File | Keyed on | Loader |
|---|---|---|---|
| Plane-Alert DB | `backend/data/plane_alert_db.json` | ICAO hex | `backend/services/fetchers/plane_alert.py:188` |
| Yacht-Alert DB | `backend/data/yacht_alert_db.json` | MMSI | `backend/services/fetchers/yacht_alert.py:25-42` |
| PLAN/CCG vessels | `backend/data/plan_ccg_vessels.json` | MMSI | `backend/services/fetchers/plan_vessel_alert.py:11-18` |

Plane-Alert carries **53 categories** with an explicit category→colour map
(`plane_alert.py:_CATEGORY_COLOR`) — USAF, other air forces, government/head-of-state,
intelligence, plus entries like `Marine One (VH-92A)`. Yacht-Alert categorises
`Tech Billionaire` / `Celebrity / Mogul` / `Oligarch Watch`.

Upstream source is the community **sdr-enthusiasts `plane-alert-db`** (a public CSV);
shadowbroker converts it offline via `backend/scripts/finalize_plane_alert_import.py` and
commits the JSON, so there is no runtime fetch and no third-party availability risk.

## Why it is worth doing

**We already have the join keys.** `military:flights:v1` records carry `hexCode`
(uppercased at `server/worldmonitor/military/v1/list-military-flights.ts:388`), and the AIS
pipeline carries MMSI. The watchlist is a lookup table over both.

**It fixes a visible quality gap.** `list-military-flights.ts:395` currently falls back to
`MILITARY_AIRCRAFT_TYPE_UNKNOWN` and `:397` to `MILITARY_OPERATOR_OTHER` for anything the
callsign heuristics miss. A hex-keyed watchlist resolves those directly.

**It is the shareable layer.** "A head-of-state aircraft just departed X" is the kind of thing
that gets screenshotted; "an unidentified contact at FL350" is not.

## Proposed work

1. Vendor the sdr-enthusiasts `plane-alert-db` CSV → JSON via a committed conversion script,
following the existing `scripts/data/*.json` curated-registry pattern. Record provenance
and license.
2. Same for the yacht and PLAN/CCG vessel lists.
3. Join on `hexCode` in the military flight pipeline and on MMSI in the AIS pipeline.
4. Surface category + operator in map popups and in the MCP military/maritime tools.
5. Add a refresh path (the upstream CSV changes) with a drift check, so the vendored copy does
not silently rot.

## Acceptance criteria

- [ ] Tracked aircraft resolve to a named operator/category from hex alone, with no callsign heuristic involved.
- [ ] Tracked vessels resolve to a named entity/category from MMSI.
- [ ] `MILITARY_AIRCRAFT_TYPE_UNKNOWN` / `MILITARY_OPERATOR_OTHER` rates measurably drop.
- [ ] Zero runtime network dependency — watchlists load from committed JSON.
- [ ] Vendored data carries provenance + license, and a staleness check flags drift from upstream.

## Related

- Keyless ADS-B redundancy issue — that widens *which* aircraft we see; this improves *what we know* about them.
- Attribution page issue (vendored dataset provenance).

Contributor guide

Open the contributing guide

Research direction

Start with server/worldmonitor/military/v1/list-military-flights.ts and the referenced plane_alert.py, yacht_alert.py, and plan_vessel_alert.py loaders to understand existing identifiers and bundled data. Then trace the AIS pipeline, map popups, and MCP military/maritime tools. Done means all three watchlists are vendored with provenance, joined without runtime networking, surfaced in relevant views and tools, and checked for upstream drift.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
data, full-stack
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.