{"id":48539860,"url":"https://github.com/tg12/phantomtide","last_synced_at":"2026-05-30T21:30:29.984Z","repository":{"id":346034619,"uuid":"1188278606","full_name":"tg12/phantomtide","owner":"tg12","description":"Global maritime intelligence platform for real-time vessel tracking, AIS data analysis, sanctions monitoring, shipping routes, port activity, anomaly detection, OSINT analytics, and geospatial insights","archived":false,"fork":false,"pushed_at":"2026-05-06T08:21:50.000Z","size":39587,"stargazers_count":82,"open_issues_count":3,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-06T10:31:55.650Z","etag":null,"topics":["airplanes","maritime","maritime-intelligence","maritime-surveillance","open-source-intelligence","sanctions"],"latest_commit_sha":null,"homepage":"https://phantom.labs.jamessawyer.co.uk/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tg12.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T21:24:39.000Z","updated_at":"2026-05-06T08:21:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tg12/phantomtide","commit_stats":null,"previous_names":["tg12/phantomtide"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/tg12/phantomtide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg12%2Fphantomtide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg12%2Fphantomtide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg12%2Fphantomtide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg12%2Fphantomtide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tg12","download_url":"https://codeload.github.com/tg12/phantomtide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg12%2Fphantomtide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33711018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["airplanes","maritime","maritime-intelligence","maritime-surveillance","open-source-intelligence","sanctions"],"created_at":"2026-04-08T04:00:25.696Z","updated_at":"2026-05-30T21:30:29.978Z","avatar_url":"https://github.com/tg12.png","language":null,"funding_links":[],"categories":["SaaS - Software as a Service","[↑](#-table-of-contents) Maritime","Cloud Service"],"sub_categories":["[↑](#-table-of-contents) GitHub","SaaS"],"readme":"# Phantom Tide\n\nCross-domain maritime and airspace intelligence from open signals.\n\n---\n\nPhantom Tide is a geospatial OSINT tool for analysts who need to answer one\nquestion quickly: what deserves attention right now, and why?\n\nIt is not just a map of feeds. It does three specific jobs:\n\n1. Rank cross-source hotspots instead of showing every signal as equal.\n2. Keep time, freshness, and degraded-state truth visible.\n3. Move from map anomaly to usable context in a few clicks.\n\nWhat is special about it:\n\n- It scores overlap between sources instead of treating every feed as a\n  separate product.\n- It defaults to a stable analyst workspace instead of a noisy auto-refreshing\n  map.\n- It treats aircraft as an analyst workflow, not just an ADS-B layer.\n- It treats maritime communications as analyst context, not just another\n  plotted feed.\n- It ships fast pivots such as proximity query, Area Intelligence Report, and\n  infrastructure-aware thermal context.\n- It exposes stale, degraded, cached, and tier-limited states directly instead\n  of quietly flattening them into a healthy-looking map.\n\nWhat this public repository is:\n\n- Public docs, release notes, screenshots, and feedback intake.\n- Not the full application codebase.\n- Use the hosted product and the docs here to evaluate the workflow and\n  release line.\n\nCurrent release: **v1.80.0**\n\nNext tracked release: **v1.81.0**\n\nTracked next-release additions:\n\n- Trusted coast-station and rescue-endpoint geometry registry to draw more\n  DSC counterpart links directly on the map.\n- Analyst filters for DSC class, counterpart type, and unresolved geometry.\n- Continued reduction of mixed-workspace ambiguity under degraded backend\n  pressure.\n\nRecent release additions:\n\n- Strategic tide stations: NOAA CO-OPS near-real-time water levels at\n  strategic ports and chokepoints, now a toggleable layer with tidal\n  prediction deviation and station context in the detail view.\n- Coastal exposure context: NASA SEDAC LECZ low-elevation coastal zone data\n  surfaces in the layers panel and in Area Intelligence Reports for the same\n  strategic port set.\n- Intel workspace briefing chips now act as retry controls: clicking a\n  delayed or stale chip reloads that specific briefing lane without a\n  full workspace reload.\n- Decision scorecard now scopes telemetry per analyst and labels the\n  visible scope explicitly. Invalid decision payloads are rejected at the\n  API boundary rather than returning silent error responses.\n- Whole-stack dependency refresh: runtime packages, infrastructure images,\n  and frontend tooling updated. GPSwise preload and FAA restricted-airspace\n  fast path restored.\n\nLive: [phantom.labs.jamessawyer.co.uk](https://phantom.labs.jamessawyer.co.uk)\n\n---\n\n## Operating Surface\n\nStart here if you want the task-shaped workflow rather than the platform brief:\n\n- Live operator guide: [phantom.labs.jamessawyer.co.uk/docs/guide/](https://phantom.labs.jamessawyer.co.uk/docs/guide/)\n- About page: [phantom.labs.jamessawyer.co.uk/about/](https://phantom.labs.jamessawyer.co.uk/about/)\n- Follow Phantom Tide on X: [x.com/_phantomtide](https://x.com/_phantomtide)\n\nThe guide explains:\n\n- how to read live, degraded, stale, and tier-limited state\n- how to work recurrent air and maritime signals through the map surface\n- how to move from spatial context into a structured briefing\n- what adapts automatically in the UI, and what stays fixed for trust\n\n## Public Restricted-Airspace Feed\n\nThe current release includes one public machine-consumable endpoint:\n\n`GET /api/public/aircraft/restricted-airspace-crossings`\n\nWhat it is for:\n\n- ingesting replay-derived restricted-airspace crossing candidates\n- polling by `sample_after` watermark\n- building a public dataset over time from a bounded rolling window\n- reading a simple who / what / where / when feed by default\n\nWhat it is not:\n\n- a live enforcement alert\n- proof of wrongdoing or regulatory violation\n- a general public archive/history API for the rest of Phantom Tide\n\nExample polling pattern:\n\n```bash\ncurl \"https://phantom.labs.jamessawyer.co.uk/api/public/aircraft/restricted-airspace-crossings?hours=24\u0026limit=100\"\ncurl \"https://phantom.labs.jamessawyer.co.uk/api/public/aircraft/restricted-airspace-crossings?sample_after=2026-04-14T12:00:00Z\"\n```\n\nDefault response shape is intentionally simple:\n\n- `quality`\n- `when`\n- `who`\n- `what`\n- `where`\n\nIf you need freshness, reference-state, and contract diagnostics, request:\n\n```bash\ncurl \"https://phantom.labs.jamessawyer.co.uk/api/public/aircraft/restricted-airspace-crossings?include_meta=true\"\n```\n\nLocal stack test:\n\n```bash\ndocker compose up --build\ncurl \"http://localhost/api/public/aircraft/restricted-airspace-crossings?hours=24\u0026limit=100\"\ncurl \"http://localhost/api/public/aircraft/restricted-airspace-crossings?sample_after=2026-04-14T12:00:00Z\"\ncurl \"http://localhost/api/public/aircraft/restricted-airspace-crossings?include_meta=true\"\n```\n\nThis public endpoint is intentionally callable without a browser session. The\nrest of the broader archive/history surface remains private or tier-gated.\n\n### Restricted-Airspace Visualization\n\n![Restricted-airspace dashboard visualization](airspace_crossing_viz/restricted_airspace_dashboard.png)\n*Replay-derived restricted-airspace crossing candidates shown as an analyst-facing\ndashboard view for public feed evaluation and external review.*\n\n### Demo Videos\n\n[![Demo 1](https://img.youtube.com/vi/lkKAVnKr6I4/hqdefault.jpg)](https://www.youtube.com/watch?v=lkKAVnKr6I4)\n\n[![Demo 2](https://img.youtube.com/vi/_ThWtQ5JG1M/hqdefault.jpg)](https://www.youtube.com/watch?v=_ThWtQ5JG1M)\n\n## Collector-Backed Context\n\nThe current release also connects collector-published datasets into the map and\ndetail workflow:\n\n- optional map layers for chokepoints, NATS airspace, ports, pipelines,\n  refineries, desalination sites, and seaport/terminal infrastructure\n- selected vessel and aircraft detail now explains nearest chokepoint,\n  infrastructure, and airspace context from loaded map layers\n- vessel and aircraft intelligence rows can include high-level dark-vessel,\n  U.S. Navy, sanctioned, military, and emergency context\n- DSC communications now feed both an analyst table and vessel-linked detail\n  context, including mapped counterpart links when the other ship or coast\n  station has usable geometry\n- artifact freshness, reuse, mixed-run state, and scan caps remain visible so\n  data presence is not confused with current or complete context\n\n## Workspace Sync And Freshness Semantics\n\nNot every source updates at the same interval.\n\n- Movement and notice feeds update frequently.\n- Environmental and reference feeds usually update every `15-60 minutes`.\n- Large reference datasets and some advisories update hourly or daily.\n- The browser now defaults to a stable manual workspace and only applies new\n  state when the analyst refreshes or explicitly enables live mode.\n- The shell still checks lightweight visible-lane change markers in the\n  background, but that does not mean the workspace itself moved.\n\nFreshness is explicit:\n\n- `Live` means the latest ingest for that source succeeded and is within its expected freshness window.\n- `Degraded` means the source answered but quality, completeness, or subtype fidelity fell.\n- `Stale` means older or cached data is still being shown for continuity and should not be treated as current truth.\n- `Tier-limited` means the feature exists but the current access level intentionally caps it.\n- `New data available` means the visible workspace changed in the backend, but\n  the current view has not applied that state yet.\n- `Live paused` means live mode is enabled, but the browser is intentionally\n  holding changes while you inspect detail, type, or manipulate the map.\n\nThe public operator guide explains how to read those states. The internal\nscheduler remains the authoritative timing source.\n\n---\n\n## Analytical Primitives\n\nPhantom Tide is built around a few product primitives rather than a long feed\ncatalog:\n\n- **Scored convergence zones**: multi-source overlap is ranked with explicit\n  contributor weights and evidence counts so the map answers where to look\n  first, not just what exists.\n- **Tracked aircraft as an analyst workflow**: aircraft are surfaced with\n  mission cues, watchlist context, alert banners, free-text quick jump, and\n  map-focus jumps rather than as a passive ADS-B layer.\n- **Communications as operational context**: DSC traffic is classified into\n  test, safety, routine, distress, and SAR-linked semantics so radio checks do\n  not read like incidents and vessel-to-counterpart links can be inspected in\n  the main workflow.\n- **Stable workspace sync**: the shell checks for visible-lane changes without\n  redrawing underneath an active investigation, and live mode pauses itself\n  while the analyst is inspecting detail or manipulating the map.\n- **Fast context pivots**: proximity query, Area Intelligence Report, thermal-\n  to-infrastructure pivots, and drill-down detail views are built to compress\n  analyst thought into a few clicks.\n\nThe value is not \"more feeds.\" The value is less analyst time spent stitching\nthose feeds together by hand.\n\n---\n\n![Phantom Tide — full dashboard overview](docs/screenshots/overview.png)\n*Global overview. The point is not that many things are happening. The point is\nwhich things should not be happening together.*\n\n---\n\n## System Surface\n\nPhantom Tide combines live telemetry, periodic advisories, historical windows,\nand reference geometry into a single operational surface.\n\n**Core capabilities:**\n\n- Cross-source global map with live and reference layers in one view\n- Ranked convergence zones built from multi-source overlap\n- Convergence cells show source-family weights, evidence counts, and trend\n- Geometry-aware rendering for points, circles, routes, and polygons\n- Intel tables for high-value notice, disruption, and advisory queues\n- DSC communications table with analyst ranking across mapped and unmapped\n  traffic, plus vessel-linked comms context in the detail panel\n- Advisory rows that jump the map to relevant coordinates without a manual search\n- Rule-based hypotheses with evidence references and confidence tiers\n- Tracked aircraft workflow with mission cues, callsign-family enrichment, watchlist context, alert banners, and free-text quick jump\n- Stable workspace sync with explicit `New data`, `Live paused`, stale-state, and manual refresh ownership\n- Space-environment context for geomagnetic and communications-disruption risk\n- Navigation-disruption attribution using environmental, notice, and orbital context together\n- Ocean-state and wind context rendered as a continuous field, not isolated station markers\n- Detail panel with observation time, ingest time, expiry, and geometry context\n- Source health reporting with explicit live, cache-backed, and failed states\n- Layer toggles that reflect stale, degraded, and down source conditions directly\n- Reference infrastructure overlays for energy, connectivity, and strategic nodes\n- Static maritime reference overlays for jurisdictional boundaries, routing measures, and infrastructure\n- Derived context in detail views: jurisdictional membership, routing context, and proximity to infrastructure\n- Thermal anomaly alerts that pivot into nearby infrastructure context\n- Proximity query and Area Intelligence Report with explicit distance ranking across all active source types\n- Vessel-in-zone correlation against watchlist and sanctioned-fleet reference data\n- Progressive zoom: dense real-time layers suppressed at world zoom, rendered on drill-down\n- Disruption events annotated with orbital visibility context to separate infrastructure effects from environmental causes\n- Deep-ocean pressure anomaly context for underwater event triage\n- Watchlist-matched entity tracking with highlight rings on active positions\n- Vessel selection can draw mapped DSC counterpart links to show who is\n  talking to whom in the current comms graph\n- Plain-language advisory popups replacing raw aviation and maritime codes\n- Single-source-of-truth tier access control with per-feature gating across starter, premium, and enterprise tiers\n- Performance: response pre-serialisation and conditional HTTP caching on high-frequency routes\n\n**Non-goals:**\n\n- It does not treat public commentary as a primary evidence class.\n- It does not collapse uncertainty into a single opaque score.\n- It does not confuse continuity of display with continuity of truth.\n\n---\n\n## Operating Thesis\n\nMost tools are good at one of these jobs:\n\n- show vessel positions\n- show aircraft positions\n- show incidents\n- show weather\n- show advisories\n\nPhantom Tide is built for the seams between them.\n\nExamples:\n\n- A vessel broadcasts position A while satellite detection suggests position B.\n- A disruption advisory is live, but environmental conditions suggest a natural explanation may be plausible.\n- Traffic disappears from a corridor while warnings and weather remain active.\n- Aircraft hold near a maritime disruption area while the sea picture below changes.\n\nThe platform is strongest when several weak signals combine into one strong\nquestion. Convergence is the triage layer for that question.\n\n---\n\n## Platform Views\n\n### Global Overview\n\n![Phantom Tide — full dashboard overview](docs/screenshots/overview.png)\n*All active layers at world zoom. Dense sources are culled until you drill in.*\n\n### Layer Controls\n\n![Layer control sidebar](docs/screenshots/sidebar.png)\n*Per-layer toggle controls with live counts, stale badges, and tier indicators.*\n\n### Risk Zones\n\n![Risk zones — Persian Gulf and Red Sea](docs/screenshots/risk_zones.png)\n*Convergence zones computed from cross-source overlap. A serious zone should\nexist because independent signals overlap, not because a designer drew it.*\n\n### Ocean State\n\n![Weather mesh — North Atlantic sensor network](docs/screenshots/weather_mesh.png)\n*Wave and wind context rendered as a continuous field for operational reading\nrather than a pile of isolated station markers.*\n\n### North Atlantic\n\n![North Atlantic — weather mesh and vessel density](docs/screenshots/atlantic.png)\n*Mid-zoom regional view. Environmental context changes how every movement\npattern should be interpreted.*\n\n### Event Detail\n\n![Event detail panel](docs/screenshots/detail_panel.png)\n*Detail view keeps source, geometry, and time semantics visible.\nA map pin without provenance is decoration.*\n\n### Advisory Detail\n\n![Advisory detail panel](docs/screenshots/detail_panel_warning.png)\n*Maritime advisory with full text, geometry, and time context in one panel.*\n\n### NOTAM Detail\n\n![NOTAM detail panel](docs/screenshots/detail_panel_notam.png)\n*Airspace notices with coordinate context. Clicking any intel row jumps the map\nand opens the detail panel without losing the table.*\n\n### Intel Tables\n\n![Intel tables panel](docs/screenshots/intel_tables.png)\n*Structured analyst tables keep high-value sources readable and actionable.*\n\n### DSC Communications\n\n![DSC communications analyst table](docs/screenshots/dsc_communications.png)\n*DSC communications are surfaced as an analyst table, not a feed-branded sidecar.\nMapped and unmapped traffic stay visible, and vessel selection can pivot that\nsame comms graph back onto the map as counterpart links. Test traffic is kept\nvisible but classified separately so it does not read like an incident queue.*\n\n![DSC communication detail](docs/screenshots/dsc_detail.png)\n*Selecting a communication opens the same right-side detail workflow used by\nthe rest of the product, with party context, telecommands, timing, analyst\nclassification, and map focus kept in one analyst surface.*\n\n![Vessel detail with DSC context](docs/screenshots/dsc_vessel_workflow.png)\n*Selecting a vessel can now pull linked DSC communications into the same\ndetail panel and draw mapped comms counterparts back onto the map, so the\noperator can see who is talking to whom without leaving the main workflow.*\n\n### Aircraft Quick Jump\n\n![Aircraft quick jump search](docs/screenshots/aircraft_search.png)\n*Free-text aircraft search resolves across loaded live tracks, alerts, and tracked/watchlist aircraft so the operator can jump straight to the right signal.*\n\n### Proximity Query\n\n![Proximity query — context menu](docs/screenshots/proximity_menu.png)\n*Right-click any map position to open a radius query.*\n\n![Proximity results](docs/screenshots/proximity_results.png)\n*Distance-ranked results across all active source types with infrastructure context.*\n\n---\n\n## Access Tiers\n\nSome deployments use a tiered access model:\n\n- **Starter** — core investigative workflow, primary live layers, advisory tables\n- **Premium** — extended reference overlays, watchlist correlation, environmental context layers, entity tracking\n- **Enterprise** — port and terminal data, highest-volume reference datasets\n\nThe public-facing instance at [phantom.labs.jamessawyer.co.uk](https://phantom.labs.jamessawyer.co.uk)\nruns at starter tier by default.\n\nTo request expanded access, use the Access button in the dashboard header or\n[open an access request](https://github.com/tg12/phantomtide/issues/new?template=access_request.md).\n\n---\n\n## Runtime Construction\n\nPhantom Tide is built as a split runtime:\n\n- a browser surface for spatial interaction and analyst workflow\n- an API path for query, gating, and evidence serving\n- a worker path for collection, normalization, scheduled refresh, and archive writes\n\nThe current implementation emphasizes deterministic operational behavior:\n\n- pre-serialized heavy responses and conditional HTTP revalidation on hot paths\n- lazy activation for dense layers rather than default full-paint behavior\n- explicit freshness, degraded, and stale-state semantics in the UI\n- modular frontend code separated by state, data, and rendering concerns\n- containerized execution with persistent runtime data and independent storage paths\n\nThird-party components and reference corpora are used under their respective\nlicenses. This README describes the product surface and runtime design, not a\ncomplete inventory of upstream inputs.\n\n---\n\n## Disclaimer\n\nAll data provided by this platform is offered \"as is\" and \"as available\",\nwithout any warranties of any kind, whether express or implied.\n\nNo guarantees are made regarding the accuracy, reliability, completeness, or\ntimeliness of the data.\n\nUsers are solely responsible for independently verifying any information before\nrelying on it for operational, navigational, legal, or commercial purposes.\n\n---\n\n## Incident Notes\n\n- [How py-spy Became a Godsend When Phantom Tide's GeoJSON Path Ate the CPU](docs/geojson-cpu-outage.md)\n- [GeoJSON CPU triage technical appendix](docs/geojson-cpu-triage.md)\n- [OOM postmortem](docs/oom-postmortem.md)\n\n---\n\n## Feedback\n\nThis repository is the public interface for feedback. Application code is not published here.\n\n| | |\n|---|---|\n| [Report a bug](https://github.com/tg12/phantomtide/issues/new?template=bug_report.md) | Something is broken or behaving unexpectedly |\n| [Request a feature](https://github.com/tg12/phantomtide/issues/new?template=feature_request.md) | A concrete capability the platform should add |\n| [Request access](https://github.com/tg12/phantomtide/issues/new?template=access_request.md) | Ask for expanded access beyond the starter tier |\n| [General feedback](https://github.com/tg12/phantomtide/issues/new?template=feedback.md) | Workflow notes, questions, or review comments |\n| [All open issues](https://github.com/tg12/phantomtide/issues) | Existing public feedback |\n\n## Follow\n\nFollow Phantom Tide on X for product updates, release notes, and new public\nworkflows:\n\n- [x.com/_phantomtide](https://x.com/_phantomtide)\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n*Phantom Tide — JS Labs*\n\n## Support\n\nIf you find this project useful, consider supporting it:\n\n| Currency | Address |\n|----------|---------|\n| **Bitcoin (BTC)** | `3QjWqhQbHdHgWeYHTpmorP8Pe1wgDjJy54` |\n| **Ethereum (ETH)** | `0x5851e6145F4773d1585b8686095FB16E368a4dA1` |\n| **ZCash (ZEC)** | `t1KSR5YkNPbjqRSCoLKo5AddFWdm9Kzxh1B` |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftg12%2Fphantomtide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftg12%2Fphantomtide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftg12%2Fphantomtide/lists"}