Compare commits

..
Author SHA1 Message Date
Antigravity AI a1f6f88ebe fix(core): resolve generic TS errors and update type definitions across plugins [Patch]
- add npx prisma generate to CI action before type checks [Patch]

- fix missing globSync import in workspace type tests [Patch]

- fix GlobeView undefined indexing for entity rendering [Patch]

- fix OSMSearchPlugin zoom property to flyToBaseDistance [Patch]

- allow getSidebarComponent to accept an optional plugin prop [Patch]

- map categories for embassies and spaceports [Patch]
2026-04-16 00:56:08 +12:00
360 changed files with 356025 additions and 7604 deletions

No files matched your search

+1 -5
View File
@@ -1,9 +1,5 @@
DATABASE_URL=file:./data/wwv.db
# Default plugins enabled on boot for demo edition
# Comma-separated list of plugin IDs
NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS=iranwarlive,satellite,gps-jamming
# Edition: "local" | "cloud" | "demo"
NEXT_PUBLIC_WWV_EDITION=local
@@ -12,4 +8,4 @@ NEXT_PUBLIC_WWV_EDITION=local
# [WARNING] NEVER commit real secrets here. Real secrets must ONLY go into .env.local!
AUTH_SECRET=changeme_d64c1f35b447da89cf6ed5a0988da1379b21904edb91a87c3f5a63942e3d23a4_changeme
-4
View File
@@ -48,10 +48,6 @@ ACLED_PASSWORD=
# Generate any random string, then set the same value in the marketplace instance config.
WWV_BRIDGE_TOKEN=
# Default plugins enabled on boot for demo edition
# Comma-separated list of plugin IDs
NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS=
# Edition: "local" | "cloud" | "demo"
NEXT_PUBLIC_WWV_EDITION=local
-2
View File
@@ -34,7 +34,6 @@ jobs:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: npx prisma generate
- run: pnpm test
build:
@@ -55,5 +54,4 @@ jobs:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: npx prisma generate
- run: pnpm build
+1 -1
View File
@@ -1,7 +1,7 @@
name: Claude Code Review
on:
pull_request:
pull_request_target:
types: [opened, synchronize, ready_for_review, reopened]
# Optional: Only run on specific file changes
# paths:
+1 -1
View File
@@ -46,5 +46,5 @@ jobs:
# Optional: Add claude_args to customize behavior and configuration
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
# or https://code.claude.com/docs/en/cli-reference for available options
# claude_args: '--allowed-tools Bash(gh pr *)'
# claude_args: '--allowed-tools Bash(gh pr:*)'
-55
View File
@@ -1,55 +0,0 @@
name: Docker Build and Publish
on:
push:
branches: [ "main", "feat/docker-ci" ]
pull_request:
branches: [ "main" ]
workflow_dispatch:
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
jobs:
build-and-push:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to the Container registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata (tags, labels) for Docker
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=raw,value=latest,enable={{is_default_branch}}
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=sha
- name: Build and push Docker image
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
-7
View File
@@ -80,13 +80,6 @@ packages/*/dist/
# Developmental scripts & temporary sandbox
/local-scripts/
/public/plugins-local/
# git worktrees
/.worktrees/
# proprietary extracted services
packages/wwv-data-engine/
# IDE workspace files
*.code-workspace
+4 -24
View File
@@ -101,13 +101,10 @@ Visibility Toggle → DataBusSubscriber subscribes to layer via WsClient
→ Store → EntityRenderer → Globe
```
Four plugin architectures exist (All-Bundle Model):
1. **Data Engine Seeder** — Standalone Fastify container with SQLite microservice or unified seeders (e.g., `iranwarlive-backend`).
2. **Dynamic CDN Loaded (Bundle)** — Externally developed plugins dynamically imported at runtime via ES module CDNs (e.g., `unpkg.com` version-pinned URLs).
3. **WWV CLI Unpacked (Dev)** — Developed externally using `@worldwideview/cli dev`, which spins up a local Vite server and hot-reloads via WebSocket injection directly into the running platform.
4. **Marketplace Package (.wwvpkg)** — Built via `@worldwideview/cli publish` and distributed through the WorldWideView Marketplace.
All plugins are now dynamically imported at runtime as ES module bundles via `loadPluginFromManifest` utilizing `import(/* webpackIgnore: true */ entry)`. The plugin passport is defined in `wwv-manifest.json` which governs its trust tier (`developer`, `unverified`, `verified`, `built-in`) and capabilities.
Three plugin architectures exist:
1. **Static** — GeoJSON file in `public/data/`, loaded by `StaticDataPlugin`
2. **Active Proxied** — Next.js API routes in `src/app/api/` as CORS proxy
3. **Microservice** — Standalone Fastify container with SQLite (e.g., `iranwarlive-backend`)
Plugin types are re-exported from SDK through `src/core/plugins/PluginTypes.ts` and `PluginManifest.ts` — **source of truth is always `@worldwideview/wwv-plugin-sdk`**.
@@ -131,18 +128,6 @@ Engine push /stream → DataBusSubscriber WsClient router
→ StackManager (co-located entity grouping)
```
### 4.3.1 Split-Routing (Cloud Fallback)
When a local engine is detected at `localhost:5001`, the frontend fetches its `/manifest` to discover available seeders. Per-plugin routing via `resolveEngineUrl`:
- Plugin's seeder is in local manifest → `ws://localhost:5001/stream`
- Plugin's seeder is NOT in local manifest → `wss://dataengine.worldwideview.dev/stream`
This enables core contributors running the public (community) engine locally to see local data for their seeders while proprietary sources (aviation, maritime) continue streaming from the cloud.
The data engine uses a **public upstream / private fork** model:
- `wwv-data-engine` (public) — community seeders, contributors fork and PR here
- `wwv-data-engine-internal` (private) — all seeders, deploys to Coolify via `git merge upstream/main`
### 4.4 Rendering Pipeline
- **Primitive-based**: Uses `PointPrimitiveCollection`, `BillboardCollection`, `LabelCollection` — NOT Cesium Entity API
@@ -212,7 +197,6 @@ Built-in plugins are instantiated in `AppShell.tsx` and registered via `PluginRe
> - **Never** reference Cursor IDE rules; we use the open `.agents/` standard.
> - **MUST**: You MUST update Semantic Versioning numbering inside the relevant `package.json` file prior to executing any code commits, adhering strictly to the `[/commit]` workflow rules (`feat:` -> Minor, `fix/refactor/perf:` -> Patch).
> - **MUST Detail Commit Levels & Bumps**: On description changes or release notes, you must detail the level of commit (Major/Minor/Fix) for *each* individual change. If there are multiple accumulated changes, you MUST EITHER commit them individually and bump the version each time, OR commit them all at once and bump the version multiple times.
> - **MUST Explain Complex Concepts Simply**: Whenever providing a complicated technical explanation to the user, you MUST include a simple explanation below it. Use an analogy with reference to the correct terminology, comparing the concept to something from everyday life to ensure the user easily understands it.
### 5.8 Workspace Hygiene
Whenever agents generate temporary debugging scripts, test REST endpoints via `.mjs`, or dump traces/JSON outputs, they **MUST** save these exclusively inside `/local-scripts/`. The root directory is strictly for production configuration files.
@@ -229,7 +213,6 @@ Whenever agents generate temporary debugging scripts, test REST endpoints via `.
| `NEXT_PUBLIC_BING_MAPS_KEY` | No | Bing Maps imagery |
| `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` | No | Google 3D Tiles |
| `NEXT_PUBLIC_WWV_EDITION` | No | `local` / `cloud` / `demo` (default: `local`) |
| `NEXT_PUBLIC_WWV_PLUGIN_DATA_ENGINE_URL` | No | Override engine WebSocket URL (default: cloud) |
| `OPENSKY_CREDENTIALS` | No | Comma-separated `id:secret` pairs for credential rotation |
| `WWV_BRIDGE_TOKEN` | No | Shared secret for marketplace → WWV install bridge |
| `WWV_DEMO_ADMIN_SECRET` | No | Demo edition admin password |
@@ -296,10 +279,7 @@ Configured in `next.config.ts` `headers()`:
| Repo | Purpose |
|---|---|
| `worldwideview` | Main application (this repo) |
| `wwv-data-engine` | Open-source data engine — community seeders (PUBLIC) |
| `wwv-data-engine-internal` | Proprietary data engine — all seeders (PRIVATE, deployed to Coolify) |
| `worldwideview-marketplace` | Plugin marketplace web app |
| `worldwideview-plugins` | Published npm plugin packages |
| `worldwideview-web` | Marketing / landing page |
---
+51 -49
View File
@@ -1,89 +1,91 @@
<div align="center">
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# WorldWideView
# WorldWideView 🌍
**The Open-Source, Plugin-Driven Geospatial Intelligence Engine**
[![License: Elastic 2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
*A modular situational awareness platform designed to ingest live data streams and render them as interactive, cinematic layers on a high-fidelity CesiumJS 3D globe.*
<!-- 📸 Replace with a high-res GIF or screenshot of the platform running with multiple layers enabled -->
![WorldWideView Interface](docs/assets/screenshot.png)
</div>
---
WorldWideView is a real-time geospatial engine visualizing live global data on an interactive 3D globe. Utilizing a dynamic "All-Bundle" plugin architecture, independent data sources—like live aircraft, maritime vessels, or conflict events—are ingested and rendered decoupled from the core 3D viewer.
## ⚡ Build a Plugin in 5 Minutes
## Core Technologies
WorldWideView’s architecture means **everything is a plugin**. The core engine is completely data-agnostic. Rather than touching complex 3D rendering code, you can build a plugin that simply pipes a REST API into GeoJSON, and the engine handles the rest!
- **Frontend:** Next.js 16 (App Router), React 19, TypeScript 5
- **3D Engine:** CesiumJS + Resium (Google Photorealistic 3D Tiles)
- **State Management:** Zustand
- **Event Bus:** Custom typed `DataBus` for high-frequency WebSocket updates
- **Database:** SQLite via Prisma (local), PostgreSQL (cloud)
- **Deployment:** Docker multi-stage build, Coolify
Ready to add a new intelligence layer (like Earthquakes, Weather, or Satellites)? We have a scaffold generator ready for you:
## Quick Start (Self-Hosting)
WorldWideView uses a multi-stage Dockerfile designed for standalone output. To deploy instantly on your own server:
**Mac/Linux:**
```bash
mkdir worldwideview && cd worldwideview
curl -fsSL https://raw.githubusercontent.com/silvertakana/worldwideview/main/setup.sh | bash
# 1. Generate the boilerplate plugin from a template
pnpm run scaffold-osm-plugin my-new-data-source
# 2. Add your data fetching logic in the generated files
# 3. Reload the dev server and watch it map on the globe!
```
**Windows (PowerShell):**
```powershell
mkdir worldwideview; cd worldwideview
Invoke-WebRequest -Uri https://raw.githubusercontent.com/silvertakana/worldwideview/main/setup.ps1 -UseBasicParsing | Invoke-Expression
```
📖 **[Read the Full Plugin Guide](docs/PLUGIN_GUIDE.md)** for a deep dive into hooking up websockets or static datasets.
> [!NOTE]
> Ensure you mount the `/app/data` volume to persist the SQLite database across container restarts.
---
## Quick Start (Local Development)
To run the source code locally for contributing or developing:
## 🚀 Installation & Setup (Local Development)
```bash
git clone https://github.com/silvertakana/worldwideview.git
cd worldwideview
pnpm install
pnpm run setup # generates .env.local with AUTH_SECRET
pnpm run dev:all # boots the UI, cache layers, and the data engine
pnpm run dev:all # starts the app, data engine, and marketplace concurrently
```
Visit `http://localhost:3000` to see the live globe.
## Plugin Ecosystem
---
WorldWideView operates on an open-core philosophy. The platform itself is data-agnostic; all data sources are dynamically imported as plugins at runtime.
## 🐋 Production Deployment (Docker & Coolify)
- **[Plugin Quickstart Guide](docs/plugin-quickstart.md)**: Learn how to scaffold and link your first plugin using the `@worldwideview/cli`.
- **[Advanced Plugin Guide](docs/plugin-advanced.md)**: Deep dive into microservice data seeders, WebSockets, complex 3D rendering, and Marketplace publishing.
WorldWideView uses a multi-stage Dockerfile designed for standalone output, natively supporting deployment via Coolify or standard Docker Compose. The `docker-compose.yml` spins up the front-end application alongside the high-performance Data Engine and Redis cache.
## Repository Ecosystem
```bash
# Start the core app, Redis cache, and Data Engine microservice in production mode
docker compose up -d
```
WorldWideView is distributed across several specialized repositories:
**Persistent Storage Requirements:**
When deploying to production, ensure you mount the following volumes to prevent data loss:
- Mount `/app/data` to persist the core SQLite database.
- Mount `/app/packages/wwv-data-engine/data` to persist the custom plugin microservices SQLite layer.
- Mount `/data` to persist the standalone Redis container.
1. **`worldwideview`** (This Repo): Main frontend, CesiumJS rendering engine, and core plugin framework.
2. **`wwv-data-engine`**: Open-source community data backend for polling public APIs.
3. **`worldwideview-plugins`**: First-party maintained plugins.
4. **`worldwideview-marketplace`**: The web application driving the plugin directory.
5. **`worldwideview-web`**: Marketing and landing site.
---
## Documentation Index
## 🧠 Core Architecture & Philosophies
Explore our comprehensive documentation suite for detailed engineering insights:
- **Modular Intelligence**: Independent plugins supply the data. The core engine remains lightweight and isolated.
- **High-Performance Rendering**: Engineered for scale using raw Cesium primitives to smoothly handle upwards of 100,000+ objects simultaneously without GPU stalls.
- **Cinematic Situational Awareness**: Implements horizon culling, smooth camera tracking, orientation-locked billboarding, and stack spiderification for dense locations.
- **[Project Overview](docs/project-overview.md)**: High-level value proposition and technology stack.
- **[Architecture](docs/architecture.md)**: DataBus event stream and Zustand state management.
- **[Build System](docs/build-system.md)**: Monorepo structure, Next.js standalone output, and Docker builds.
- **[Development](docs/development.md)**: Coding conventions and common implementation patterns.
- **[Testing](docs/testing.md)**: Vitest setup and coverage targets.
- **[Deployment](docs/deployment.md)**: Coolify integration and persistent volumes.
- **[Files Catalog](docs/files.md)**: Comprehensive mapping of core source files.
---
## 📚 Documentation Index
- **[Setup & Installation Guide](docs/SETUP.md)**: Detailed environment and local development setup.
- **[Architecture (Engineering Depth)](docs/ARCHITECTURE.md)**: Deep dive into the Cesium rendering pipeline, event data bus, and performance optimizations.
- **[Contributions Guide](CONTRIBUTING.md)**: How to help out, coding standards, and commit conventions.
- **[User Guide](docs/USER_GUIDE.md)**: Application features and navigation tips.
---
## 🤝 Contributing & Community
We are actively looking for contributors to help build new data plugins and optimize the core 3D engine!
- Found a bug or have an idea? Search the [Issue Tracker](https://github.com/silvertakana/worldwideview/issues) and submit a report.
- Want to build something? Check out our **[Pinned Plugin Wishlist](https://github.com/silvertakana/worldwideview/issues)** for great first issues!
> [!IMPORTANT]
> **Fair-Use Notice:** This application may contain copyrighted material the use of which has not always been specifically authorized by the copyright owner. Such material is made available for educational purposes, situational awareness, and to advance understanding of global events under "fair use" (Section 107 of the US Copyright Law).
+5 -17
View File
@@ -54,19 +54,7 @@ Each stage is **self-contained and demo-able**. Any stage can be shipped indepen
---
## Stage 5: AI & Sharing Features (Immediate User Value)
**Demo:** "Chat with the AI to explore the globe, record a narrated briefing, and share the view via a URL."
- [ ] Unified Data Format schema (WWVDocument) with snapshot radius bounding
- [ ] Base64url view link sharing (`#v=...`)
- [ ] Shared `ActionExecutor` core for Animation & Copilot
- [ ] Animation Engine (TrackScheduler, Player, overlays, TTS voice)
- [ ] MCP Server (tools wrapping the action vocabulary)
- [ ] Hybrid Spatial Awareness (Pre-computed summaries + MCP spatial query tools)
---
## Stage 6: Publisher Workflow
## Stage 5: Publisher Workflow
**Demo:** "A plugin author submits their plugin. After review, it appears in the catalog."
- [ ] Marketplace user accounts (Supabase Auth — email/password + GitHub OAuth)
@@ -78,7 +66,7 @@ Each stage is **self-contained and demo-able**. Any stage can be shipped indepen
---
## Stage 7: Cloud Platform & Accounts
## Stage 6: Cloud Platform & Accounts
**Demo:** "User registers, gets [user].app.worldwideview.dev, installs plugins from marketplace."
- [ ] `app.worldwideview.dev` — auth/register/dashboard
@@ -93,7 +81,7 @@ Each stage is **self-contained and demo-able**. Any stage can be shipped indepen
---
## Stage 8: Built-In Data Services
## Stage 7: Built-In Data Services
**Demo:** "Aviation and maritime data with full history, served from api.worldwideview.dev."
- [ ] `api.worldwideview.dev` — aviation/maritime polling + persistence
@@ -105,7 +93,7 @@ Each stage is **self-contained and demo-able**. Any stage can be shipped indepen
---
## Stage 9: Trust Tiers, Extensions & Polish
## Stage 8: Trust Tiers, Extensions & Polish
**Demo:** "Install a verified extension plugin that adds cockpit view to aviation."
- [x] Ed25519-signed plugin registry (`GET /api/registry` on marketplace)
@@ -123,7 +111,7 @@ Each stage is **self-contained and demo-able**. Any stage can be shipped indepen
---
## Stage 10: Infrastructure & Monetization
## Stage 9: Infrastructure & Monetization
**Demo:** "Buy Pro, paste license key, unlock snapshot history and higher rate limits."
- [ ] Coolify on ThinkPad T480s — deploy all services
-7
View File
@@ -1,7 +0,0 @@
# This file lists tools managed by Aftman, a cross-platform toolchain manager.
# For more information, see https://github.com/LPGhatguy/aftman
# To add a new tool, add an entry to this table.
[tools]
rojo = "rojo-rbx/[email protected]"
# rojo = "rojo-rbx/[email protected]"
-1
View File
@@ -1 +0,0 @@
{"message":"fix(aviation): implement exponential backoff for rate limits","tree":"55c74a09dac7ce178ecf94d5cb48b2502e57e759","parents":["e25ddc0b648b757ea32b7376bab50d8e75d6d330"]}
-54
View File
@@ -1,54 +0,0 @@
const fs = require("fs");
const { execSync } = require("child_process");
const uuidsToDelete = [
"i331gbc1zzytx7via8lntdm6",
"pow71xsobdas7etf5r3hy5ug",
"l79dyd03lhtcpgi7swkoxm55",
"ry6160tpy4gh2xjfwr011no0",
"gfe78t8jm53lltentz19ze60",
"e1cg7q8khyvpti5rkp351559",
"c35cvvqxhdbslk8yc24g04wk",
"ijj9pqkavlusy2wmzsbjtc74",
"ghe6bzlr6ex6j51lgxzyhd46",
"h3v45w2u1essulzeg56i27a3",
"oxk05amog4fla0lskmkfx64x",
"yxm4mn60lfp9qah0q4yf2hij",
"ezjxo4ehs96lv0ji1n2r0auw",
"t12x7pgptsqiu5gbvv35gun5",
"urq1ll00a3vv9on6pulmpofe",
"eb5zgw5wlgvio2gggbiphpam",
"ld1h3pody4nxj3b44pbskl53",
"x111xfygqxrlbf5wqlx59f6d",
"se1weqr4dj7thp4p1l055wfc",
"cqses6urxff0n94i0u6lktzt",
"nvcir33nyuvzk5niy3s7eg9w",
"s63onga2s6v8r3k10lrdwzth",
"cf3uedqnjmwv48h7tm91d95r",
"o9124dnnieau9wxoefyxvfgu",
"kxzobc8qlvigbsk1d35dpiyi",
"eh8lzjbsy2c9kwj2emztcmf6",
"umfsos2vcmotfk2cfpqdoycc",
"yn1mdh0fngiati6r4625qvv9"
];
const token = "1|vPZPgvB8vVi8ZD5ZKS8lrCrwNlPofVv4I8Tjmqmyd01f92d2";
const baseUrl = "https://coolify.worldwideview.dev/api/v1";
const appUuid = "nmn55t4io3myfubs72worn7k";
async function run() {
for (const id of uuidsToDelete) {
console.log("Deleting", id);
try {
const res = await fetch(`${baseUrl}/applications/${appUuid}/envs/${id}`, {
method: "DELETE",
headers: { "Authorization": `Bearer ${token}` }
});
console.log(id, res.status);
} catch(e) {
console.error(e);
}
}
}
run();
+38
View File
@@ -13,8 +13,46 @@ services:
- "WWV_DEMO_ADMIN_SECRET=${WWV_DEMO_ADMIN_SECRET:-}"
- "WWV_BRIDGE_TOKEN=${WWV_BRIDGE_TOKEN:-}"
wwv-data-engine:
build:
context: .
dockerfile: ./packages/wwv-data-engine/Dockerfile
ports:
- "5001:5001"
volumes:
- engine-data:/app/packages/wwv-data-engine/data
restart: always
depends_on:
- redis
env_file:
- path: .env
required: false
environment:
- "NODE_ENV=production"
- "REDIS_URL=${REDIS_URL:-redis://redis:6379}"
networks:
- coolify
- default
labels:
- "traefik.enable=true"
- "traefik.http.routers.data-engine.rule=Host(`dataengine.worldwideview.dev`)"
- "traefik.http.routers.data-engine.entrypoints=websecure"
- "traefik.http.routers.data-engine.tls=true"
- "traefik.http.routers.data-engine.tls.certresolver=letsencrypt"
- "traefik.http.services.data-engine.loadbalancer.server.port=5001"
redis:
image: redis:7-alpine
restart: always
ports:
- "6379:6379"
volumes:
- redis-data:/data
volumes:
wwv-data:
engine-data:
redis-data:
networks:
coolify:
+91
View File
@@ -0,0 +1,91 @@
# API Reference
This document provides a technical reference for the core internal services of WorldWideView. These services are designed to be used by plugins and core components for communication and data management.
## `DataBus`
The `DataBus` is a central event emitter used for decoupled, typed communication between different parts of the application.
- **Import**: `import { dataBus } from "@/core/data/DataBus";`
- **Source**: `src/core/data/DataBus.ts`
### Methods
#### `on<K>(event: K, handler: Handler): () => void`
Subscribes to an event. Returns an unsubscribe function.
- **event**: The event name (keys of `DataBusEvents`).
- **handler**: A callback function receiving the event data.
#### `off<K>(event: K, handler: Handler): void`
Unsubscribes from an event.
- **event**: The event name.
- **handler**: The handler function to remove.
#### `emit<K>(event: K, data: T): void`
Broadcasts an event to all subscribers.
- **event**: The event name.
- **data**: The payload for the event.
#### `removeAllListeners(event?: string): void`
Removes all listeners for a specific event, or all listeners if no event is provided.
---
## `PluginRegistry`
The `PluginRegistry` manages the registration and discovery of all `WorldPlugin` implementations.
- **Import**: `import { pluginRegistry } from "@/core/plugins/PluginRegistry";`
- **Source**: `src/core/plugins/PluginRegistry.ts`
### Methods
#### `register(plugin: WorldPlugin): void`
Adds a new plugin to the registry. Throws a warning if the plugin ID is already registered.
#### `get(pluginId: string): WorldPlugin | undefined`
Retrieves a plugin by its unique ID.
#### `getAll(): WorldPlugin[]`
Returns an array of all registered plugins.
#### `getByCategory(category: string): WorldPlugin[]`
Returns all plugins belonging to a specific category.
#### `has(pluginId: string): boolean`
Checks if a plugin with the given ID is registered.
#### `unregister(pluginId: string): void`
Removes a plugin from the registry.
---
## `CacheLayer`
The `CacheLayer` provides a two-tier caching mechanism for geographical entities.
- **Import**: `import { cacheLayer } from "@/core/data/CacheLayer";`
- **Source**: `src/core/data/CacheLayer.ts`
### Methods
#### `init(): Promise<void>`
Initializes the IndexedDB store. Must be called before persistent storage operations.
#### `set(pluginId: string, entities: GeoEntity[], ttlMs?: number): void`
Caches entities for a plugin.
- **pluginId**: Unique identifier for the data source.
- **entities**: Array of `GeoEntity` objects.
- **ttlMs**: Time-to-live in milliseconds (default: 30,000).
#### `get(pluginId: string): GeoEntity[] | null`
Retrieves entities from the L1 (Memory) cache. Returns `null` if expired or missing.
#### `getFromPersistent(pluginId: string): Promise<GeoEntity[] | null>`
Retrieves entities from the L2 (IndexedDB) cache. This method also populates the L1 cache on success.
#### `invalidate(pluginId: string): void`
Removes entries for a plugin from both L1 and L2 caches.
#### `clear(): void`
Purges all data from both cache tiers.
+56 -27
View File
@@ -1,33 +1,62 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Architecture
# System Architecture
## Overview
WorldWideView operates on a decoupled, plugin-based architecture designed for real-time visualization of geospatial data. The system is split between a Next.js 16 frontend that handles UI and CesiumJS 3D rendering, and a network of plugin data seeders that stream live updates via WebSockets.
WorldWideView is a high-performance, event-driven geospatial intelligence engine. It is designed to ingest live, fast-moving signals—such as aviation ADS-B, maritime AIS, or satellite feeds—and transform them into cinematic, real-time visual layers on a 3D globe.
The core design philosophy is the "All-Bundle Model," where plugins are dynamically imported at runtime as ES module bundles (`Dynamic CDN Loaded`). The frontend maintains a modular state architecture using Zustand, routing high-frequency data updates through a custom `DataBus` singleton to avoid React render cycle bottlenecks.
## Module Breakdown
## Component Map
- **Frontend App Shell:** Next.js App Router providing layout and base API routes (in `src/app/`).
- **Globe Rendering Engine:** CesiumJS wrapped in Resium, responsible for 3D primitive and model rendering (in `src/core/globe/`).
- **State Management:** Zustand slice-based architecture (in `src/core/state/`).
- **Data Pipeline:** Custom event bus (`DataBus`) and WebSocket clients (`DataBusSubscriber`) routing live data to state (in `src/core/data/`).
- **Plugin System:** Registration, lifecycle management, and ES module loaders (in `src/core/plugins/`).
- **Database Layer:** Prisma ORM connecting to local SQLite or cloud PostgreSQL (in `prisma/`).
1. **`src/core/plugins`**: The registration and lifecycle management layer. Defines how plugins are booted and destroyed.
2. **`src/core/data`**: The "Heartbeat" of the system.
- **DataBus**: Decentralized event pipeline for all system actions.
- **PollingManager**: Intelligent scheduler for external API calls with backoff logic.
- **CacheLayer**: 2-stage persistent caching (In-Memory + IndexedDB).
3. **`src/core/globe`**: The Rendering Engine.
- **Cesium Integration**: Low-level control over the Cesium Viewer.
- **EntityRenderer**: High-performance "Primitive" renderer.
4. **`src/plugins`**: Domain-specific logic (Aviation, Maritime, etc.).
## Key Files
- `src/core/plugins/PluginManager.ts` - The PluginManager class. Core registry that instantiates plugins, calls `initialize()`, and handles lifecycle events.
- `src/core/plugins/loaders/InstalledPluginsLoader.ts` - Dynamically fetches and imports `import(/* webpackIgnore: true */ ...)` marketplace plugins into the environment.
- `src/core/data/DataBus.ts` - Custom typed event bus singleton that routes high-frequency data around the application.
- `src/core/globe/GlobeView.tsx` - The main Cesium viewer container, handling imagery layers, cameras, and primitive collections.
- `src/core/state/store.ts` - The main Zustand store registry linking the nine state slices (globe, layers, timeline, ui, filter, data, config, favorites, geojson).
## Performance: Primitives vs. Entities
## Data Flow
Real-time data follows a strict unidirectional stream optimized for sub-second updates:
One of our core design decisions is using **Cesium Primitives** instead of the standard high-level **Entity API** for high-count datasets.
1. **Engine Push:** A remote data engine pushes state over WebSocket (`/stream`) from either local seeders (`ws://localhost:5001/stream`) or the cloud fallback (`wss://dataengine.worldwideview.dev/stream`).
2. **WebSocket Client Router:** `WsClient.handleMessage()` receives the payload and pipes it to the event bus.
3. **DataBus Emission:** The bus fires `DataBus.emit("websocketData", WsStreamPayload)`.
4. **State Hydration:** The `DataBusSubscriber` component listens to the bus and calls `_hydrateSnapshot()` to update the Zustand store's `entitiesByPlugin` cache.
5. **Memoized Selection:** `GlobeView` selects the visible entities from the store.
6. **Primitive Rendering:** The `EntityRenderer` translates store entities into Cesium `PointPrimitiveCollection` and `BillboardCollection` arrays for GPU rendering.
7. **Animation & LOD:** `AnimationLoop` handles horizon culling and hover effects, while `useModelRendering` promotes close-range entities to 3D glTF models.
| Feature | Entity API | Primitive API (WWV) |
|---|---|---|
| **Abstraction** | High (Easy to use) | Low (Direct GPU access) |
| **Overhead** | Significant per-entity JS objects | Minimal (Batched rendering) |
| **Max Capacity** | ~1,000 entities | **100,000+ points/billboards** |
| **WWV Use Case** | Info window content | Live data point visualization |
**Why?** The Entity API in Cesium is great for rich features but triggers significant CPU overhead when managing thousands of moving objects. By using `PointPrimitiveCollection` and `BillboardCollection`, WorldWideView batches these draw calls, ensuring 60FPS even with dense global data.
## Data Pipeline (Example: Aviation)
The following diagram trace the journey of a single data point from a remote sensor to the user's screen:
```mermaid
sequenceDiagram
participant S as Remote API (e.g. OpenSky)
participant P as Plugin (AviationPlugin)
participant D as DataBus
participant R as EntityRenderer
participant G as GPU (Cesium)
Note over S, P: Polling Interval (e.g. 30s)
S->>P: raw JSON data
rect rgb(200, 230, 255)
Note right of P: Mapping to GeoEntity
P->>P: parse, filter, sanitize
end
P->>D: emit("dataUpdated", { entities })
D->>R: trigger render cycle
rect rgb(255, 230, 200)
Note right of R: Batch Update Primitives
R->>G: update collection buffer
end
G-->>G: 60FPS visualization
```
## Design Principles
- **Single Responsibility (SRP)**: Plugins only handle data mapping; they don't know about the UI or the Cache.
- **Dependency Inversion**: The `PluginManager` communicates with plugins through the `WorldPlugin` interface, allowing new plugins to be added without modifying core code.
- **Event-Driven Architecture**: The system is reactive. Components subscribe to what they need, reducing prop-drilling and unnecessary re-renders.
- **Defensive Programming**: All external API calls in plugins are wrapped in error boundaries and handled by the `PollingManager`'s backoff logic to prevent system-wide failures.
+452
View File
@@ -0,0 +1,452 @@
# WorldWideView Plugin Guide
Build custom data layer plugins for the WorldWideView 3D globe platform. This guide covers the full plugin lifecycle, available APIs, and step-by-step instructions for creating your own plugin.
## Architecture Overview
```
┌─────────────────────────────────────────────────┐
│ UI Layer │
│ LayerPanel ─ InfoCard ─ Timeline ─ ConfigPanel │
└────────────────────┬────────────────────────────┘
│ Zustand Store
┌────────────────────┴────────────────────────────┐
│ Plugin Manager │
│ register → initialize → enable/disable → poll │
│ ┌────────┴────────┐ │
│ PluginRegistry PollingManager │
│ │ │ │
│ DataBus (events) CacheLayer (2-tier) │
└────────────────────┬────────────────────────────┘
│
┌────────────────────┴────────────────────────────┐
│ Your Plugin (WorldPlugin) │
│ fetch() → GeoEntity[] → renderEntity() → Globe │
└─────────────────────────────────────────────────┘
```
### Plugin Lifecycle
1. **Instantiation**: Your class is instantiated and passed to `pluginRegistry.register()`.
2. **Registration**: The `PluginManager` discovers the plugin in the registry during the boot sequence.
3. **Initialization**: `initialize(ctx)` is called. This is where you should set up your domain-specific API clients or static data.
4. **Enabled State**: When a user toggles the layer in the UI, the `PluginManager` starts the polling cycle.
5. **Fetch/Render Cycle**: `fetch()` is called periodically; `renderEntity()` is called for result.
6. **Destruction**: `destroy()` is called if the plugin is unregistered or the application is unmounted.
### Data Flow
```mermaid
sequenceDiagram
participant PM as PluginManager
participant P as YourPlugin
participant DB as DataBus
PM->>P: initialize(ctx)
Note over PM, P: User toggles layer ON
loop Every getPollingInterval()
PM->>P: fetch(timeRange)
P-->>PM: GeoEntity[]
PM->>DB: emit("dataUpdated")
end
Note over PM, P: User toggles layer OFF
PM->>PM: Stop Polling
```
---
## Quick Start: Minimal Plugin
```typescript
// src/plugins/earthquakes/index.ts
import { Activity } from "lucide-react";
import type {
WorldPlugin, GeoEntity, TimeRange, PluginContext,
LayerConfig, CesiumEntityOptions,
} from "@/core/plugins/PluginTypes";
export class EarthquakePlugin implements WorldPlugin {
id = "earthquake";
name = "Earthquakes";
description = "Recent seismic activity from USGS";
icon = Activity;
category = "natural-disaster" as const;
version = "1.0.0";
private context: PluginContext | null = null;
async initialize(ctx: PluginContext): Promise<void> {
this.context = ctx;
}
destroy(): void {
this.context = null;
}
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
const res = await fetch("/api/earthquake");
if (!res.ok) return [];
const data = await res.json();
return data.features.map((f: any): GeoEntity => ({
id: `earthquake-${f.id}`,
pluginId: "earthquake",
latitude: f.geometry.coordinates[1],
longitude: f.geometry.coordinates[0],
altitude: 0,
timestamp: new Date(f.properties.time),
label: `M${f.properties.mag}`,
properties: {
magnitude: f.properties.mag,
depth: f.geometry.coordinates[2],
place: f.properties.place,
},
}));
}
getPollingInterval(): number {
return 120000; // 2 minutes
}
getLayerConfig(): LayerConfig {
return {
color: "#ef4444",
clusterEnabled: true,
clusterDistance: 40,
};
}
renderEntity(entity: GeoEntity): CesiumEntityOptions {
const mag = (entity.properties.magnitude as number) || 0;
return {
type: "point",
color: mag >= 5 ? "#dc2626" : mag >= 3 ? "#f97316" : "#fbbf24",
size: Math.max(4, mag * 2),
outlineColor: "#000000",
outlineWidth: 1,
};
}
}
```
### Register Your Plugin
In your app's initialization code (e.g. the root layout component):
```typescript
import { pluginRegistry } from "@/core/plugins/PluginRegistry";
import { EarthquakePlugin } from "@/plugins/earthquakes";
pluginRegistry.register(new EarthquakePlugin());
```
That's it. The plugin will appear in the Layer Panel and can be toggled on/off.
---
## WorldPlugin Interface Reference
### Required Properties
| Property | Type | Description |
|---|---|---|
| `id` | `string` | Unique identifier (e.g. `"aviation"`, `"earthquake"`) |
| `name` | `string` | Display name shown in the Layer Panel |
| `description` | `string` | Short description shown below the name |
| `icon` | `string \| ComponentType` | Lucide icon component or emoji string |
| `category` | `PluginCategory` | Grouping in the Layer Panel |
| `version` | `string` | Semver version string |
**Available categories:** `aviation`, `maritime`, `conflict`, `natural-disaster`, `infrastructure`, `cyber`, `economic`, `custom`
### Required Methods
#### `initialize(ctx: PluginContext): Promise<void>`
Called once when the plugin is registered. Store the context for later use.
```typescript
interface PluginContext {
apiBaseUrl: string; // Base URL for API calls
timeRange: TimeRange; // Current time window
onDataUpdate: (entities: GeoEntity[]) => void; // Push data updates
onError: (error: Error) => void; // Report errors
}
```
#### `destroy(): void`
Cleanup when the plugin is unregistered. Release any resources.
#### `fetch(timeRange: TimeRange): Promise<GeoEntity[]>`
Called by the polling system at your declared interval. Return an array of `GeoEntity` objects representing your data points.
#### `getPollingInterval(): number`
Return the polling interval in milliseconds. This determines how often `fetch()` is called.
#### `getLayerConfig(): LayerConfig`
Return the default layer configuration. These values are used to initialize the UI and the renderer:
```typescript
interface LayerConfig {
color: string; // Default CSS color for primary visualization
iconUrl?: string; // Default icon for billboards (if applicable)
clusterEnabled: boolean; // Enable spatial clustering at high zoom levels
clusterDistance: number; // Cluster radius in pixels (suggested: 40)
minZoomLevel?: number; // Hide entities when camera is too far (meters)
maxEntities?: number; // Limit for performance safety
showLabelsByDefault?: boolean; // If true, labels show without hover
}
```
#### `renderEntity(entity: GeoEntity): CesiumEntityOptions`
Called for each entity to determine how it appears on the globe:
```typescript
interface CesiumEntityOptions {
type: "billboard" | "point" | "polyline" | "polygon" | "label";
color?: string; // CSS color string
size?: number; // Pixel size (for points)
iconUrl?: string; // Image URL (for billboards)
rotation?: number; // Degrees, applied to billboards
outlineColor?: string; // CSS color for point outlines
outlineWidth?: number; // Outline width in pixels
labelText?: string; // Text label above the entity
labelFont?: string; // CSS font string for labels
}
```
### Optional Methods
#### `getSelectionBehavior(entity: GeoEntity): SelectionBehavior | null`
Return trail rendering and camera behavior when an entity is selected. Return `null` for default behavior.
```typescript
interface SelectionBehavior {
showTrail?: boolean; // Render a trail polyline
trailDurationSec?: number; // Trail length in seconds (default: 60)
trailStepSec?: number; // Trail point spacing (default: 5)
trailColor?: string; // CSS color (default: '#00fff7')
flyToOffsetMultiplier?: number; // Camera offset multiplier (default: 3)
flyToBaseDistance?: number; // Base camera distance in meters (default: 30000)
}
```
**Example:** Show trails only for airborne entities:
```typescript
getSelectionBehavior(entity: GeoEntity): SelectionBehavior | null {
if (entity.properties.on_ground) return null;
return { showTrail: true, trailColor: "#00fff7" };
}
```
#### `getServerConfig(): ServerPluginConfig`
Declare your plugin's server-side data layer requirements:
```typescript
interface ServerPluginConfig {
apiBasePath: string; // e.g. "/api/aviation"
pollingIntervalMs: number; // Server-side polling interval
requiresAuth?: boolean; // OAuth/API key needed
historyEnabled?: boolean; // Supports timeline playback
availabilityEnabled?: boolean; // Reports time ranges
}
```
> **Note:** The current server infrastructure (API routes, background polling) is set up per-plugin in `src/app/api/<pluginId>/` and `src/lib/`. See [Server-Side Data Layer](#server-side-data-layer) for the pattern.
#### `getSidebarComponent(): ComponentType`
Return a React component to render in the sidebar when this plugin's layer is active.
#### `getDetailComponent(): ComponentType<{ entity: GeoEntity }>`
Return a React component to render in the detail panel when an entity from this plugin is selected.
---
## GeoEntity
The universal data model for all plugin entities:
```typescript
interface GeoEntity {
id: string; // Unique ID (prefix with pluginId)
pluginId: string; // Must match your plugin's `id`
latitude: number; // WGS84 latitude
longitude: number; // WGS84 longitude
altitude?: number; // Meters above sea level
heading?: number; // Degrees (0 = North, 90 = East)
speed?: number; // Meters per second
timestamp: Date; // When this data was captured
label?: string; // Short display label
properties: Record<string, unknown>; // Plugin-specific data
}
```
**Conventions:**
- **`id`** — Prefix with your plugin ID to avoid collisions: `"earthquake-us7000abc"`
- **`heading` + `speed`** — If both are set, the renderer will extrapolate movement between polls (smooth animation)
- **`properties`** — Use for domain-specific data (e.g. magnitude, vessel type, altitude). These are accessible in info cards and detail panels
---
## Core Services
### DataBus — Event Communication
Subscribe to cross-plugin events:
```typescript
import { dataBus } from "@/core/data/DataBus";
// Available events
dataBus.on("dataUpdated", ({ pluginId, entities }) => { ... });
dataBus.on("entitySelected", ({ entity }) => { ... });
dataBus.on("layerToggled", ({ pluginId, enabled }) => { ... });
dataBus.on("timeRangeChanged", ({ timeRange }) => { ... });
dataBus.on("cameraPreset", ({ presetId }) => { ... });
```
### CacheLayer — Two-Tier Caching
The PluginManager automatically caches your `fetch()` results in:
1. **Memory** — instant recall within the same session
2. **IndexedDB** — survives page refreshes
You don't need to interact with the cache directly — it's managed by the PluginManager.
### PollingManager — Automatic Polling
Your `getPollingInterval()` return value is used to set up automatic polling. Features:
- **Exponential backoff** on errors (up to 60s max)
- **Pause/resume** support
- **Dynamic interval updates** — users can adjust intervals in the Config Panel
---
## Server-Side Data Layer
For plugins that need server-side processing (API proxying, database persistence, authentication), follow this pattern:
### 1. Create an API Route
```
src/app/api/<your-plugin>/route.ts
```
```typescript
import { NextResponse } from "next/server";
export async function GET() {
// Fetch from your data source
const res = await fetch("https://api.example.com/data", {
headers: { "Authorization": `Bearer ${process.env.YOUR_API_KEY}` },
cache: "no-store",
});
if (!res.ok) {
return NextResponse.json({ error: res.statusText }, { status: res.status });
}
const data = await res.json();
return NextResponse.json(data);
}
```
### 2. Optional: Background Polling
For APIs with rate limits, create a server-side polling module:
```
src/lib/<your-plugin>-polling.ts
```
Register it in `src/instrumentation.ts`:
```typescript
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
const { startYourPluginPolling } = await import("./lib/your-plugin-polling");
startYourPluginPolling();
}
}
```
### 3. Optional: History Endpoint
For timeline/playback support, add a history route:
```
src/app/api/<your-plugin>/history/route.ts
```
Accept a `?time=<ms>` parameter and return the closest historical records.
### 4. Declare in Plugin
Use `getServerConfig()` to document your server-side setup:
```typescript
getServerConfig(): ServerPluginConfig {
return {
apiBasePath: "/api/earthquake",
pollingIntervalMs: 120000,
historyEnabled: false,
};
}
```
---
## Rendering Details
### Billboard vs Point
| Feature | `billboard` | `point` |
|---|---|---|
| Custom image | Yes via `iconUrl` | No |
| Rotation | Yes via `rotation` | No |
| Performance | Good (GPU batched) | Best (single draw call) |
| Outline | No | Yes via `outlineColor/Width` |
**Use billboards** for entities with custom icons and rotation (aircraft, vehicles).
**Use points** for simpler markers (fires, earthquakes, vessels).
### Labels
Labels are automatically hidden at long distances and shown within 500km or on hover/selection. Configure via `labelText` and `labelFont` in your `renderEntity()` return.
### Position Extrapolation
If your `GeoEntity` has both `heading` and `speed` set, the globe renderer will automatically extrapolate smooth movement between polling intervals (up to 5 minutes). This creates fluid animation without increasing your API call frequency.
---
## Existing Plugin Examples
| Plugin | Category | Data Source | Rendering | Selection |
|---|---|---|---|---|
| [Aviation](../src/plugins/aviation/index.ts) | `aviation` | OpenSky Network (live + Supabase fallback) | Billboards with altitude-based coloring | Trail polyline for airborne entities |
| [Maritime](../src/plugins/maritime/index.ts) | `maritime` | AIS feeds (with demo fallback) | Points with vessel-type coloring | Default |
| [Wildfire](../src/plugins/wildfire/index.ts) | `natural-disaster` | NASA FIRMS (VIIRS) | Points with FRP-based sizing/coloring | Default |
---
## Checklist: Publishing a Plugin
- [ ] Implements all required `WorldPlugin` methods
- [ ] `id` is unique and lowercase (no spaces)
- [ ] All `GeoEntity.id` values are prefixed with your plugin ID
- [ ] `GeoEntity.pluginId` matches your plugin's `id`
- [ ] `renderEntity()` returns valid `CesiumEntityOptions`
- [ ] API route created (if needed) at `src/app/api/<id>/`
- [ ] Plugin registered in the app initialization code
- [ ] Tested: toggle on/off in Layer Panel
- [ ] Tested: entity hover and click selection
- [ ] Tested: info card displays your `properties` correctly
+75
View File
@@ -0,0 +1,75 @@
# Setup & Installation
Follow these steps to set up your development environment and get WorldWideView running locally.
## Requirements
- **Node.js**: v18.17 or higher (tested on v20+)
- **pnpm**: v8 or higher (`npm install -g pnpm`)
- **Browser**: Chrome, Firefox, or Edge (CesiumJS requires WebGL support)
## Environment Setup
Run the setup script to auto-generate `.env.local` with a secure `AUTH_SECRET`:
```bash
pnpm run setup
```
This copies `.env.example` → `.env.local` and fills in `AUTH_SECRET` automatically. You can then optionally add API keys for enhanced features (Cesium Ion, Bing Maps, OpenSky, etc.).
> [!NOTE]
> `AUTH_SECRET` must remain stable across restarts. The setup script generates it once and writes it to `.env.local`. Never commit `.env.local` to git.
## Running Locally
1. **Install Dependencies**:
```bash
pnpm install
```
2. **Generate environment file** (first time only):
```bash
pnpm run setup
```
3. **Start Dev Server**:
```bash
pnpm run dev:all
```
4. **Open Browser**:
Navigate to [http://localhost:3000](http://localhost:3000).
## Folder Structure Explanation
Understanding the project layout:
```text
worldwideview/
├── docs/ # Project documentation
├── packages/ # Plugin packages (pnpm workspaces)
├── public/ # Static assets (GeoJSON data files, Cesium dependencies)
├── scripts/ # Build and utility scripts (e.g., copy-cesium.mjs)
└── src/
├── app/ # Next.js App Router (Layouts, Pages, API Routes)
├── components/ # React UI components (HUD, LayersPanel, Panels)
├── core/ # Core engine logic
│ ├── data/ # Data management (DataBus, Polling, Cache)
│ ├── globe/ # Cesium-specific hooks and view logic
│ └── plugins/ # Plugin system base and registry
├── lib/ # Utility libraries and server-side logic
└── plugins/ # Built-in plugins (Aviation, Maritime, etc.)
```
## Verification
To verify your setup:
1. Ensure the globe loads without errors in the console.
2. Check if the "Aviation" layer is visible in the Layers Panel.
3. Verify that the HUD (top bar) displays live camera coordinates.
---
> [!TIP]
> The database is created automatically on first run — no manual setup is required. If you need to reset it, delete `data/wwv.db` and restart the dev server.
+48
View File
@@ -0,0 +1,48 @@
# User Guide
Welcome to WorldWideView! This guide will help you navigate the 3D globe and interact with live data layers.
## Navigating the Globe
- **Rotate**: Left-click and drag.
- **Zoom**: Use the mouse wheel or pinch on a trackpad.
- **Tilt/Rotate Perspective**: Right-click and drag (or use Ctrl + Left-click).
- **Fly to Location**: Double-click on an entity or use the search bar (if available).
## Application Panels
### Layers Panel
Located on the left side of the screen, the Layers Panel allows you to toggle different data sources on and off.
- **Search Layers**: Filter the available plugins.
- **Toggle Visibility**: Enable or disable specific data layers like Aviation, Maritime, or Wildfires.
- **Layer Configuration**: Some layers provide settings like clustering or color customization.
### HUD (Heads-Up Display)
The HUD at the top provides real-time information about your current view:
- **Camera Coordinates**: Latitude, Longitude, and Altitude.
- **Pitch & Heading**: Current orientation of the camera.
- **FPS Indicator**: Performance metrics.
### Timeline
The timeline at the bottom allows you to track data over time.
- **Current Time**: Displays the simulated time on the globe.
- **Playback Controls**: If supported by the plugin, you can scrubbing through historical data.
## Interacting with Entities
- **Hover**: Hover over a marker (point or billboard) to see a quick label.
- **Selection**: Click on an entity to open its **Info Card**.
- **Info Card**: Displays detailed properties about the selected object (e.g., flight number, vessel type, fire intensity).
- **Trails**: Some entities (like aircraft) show a historical trail when selected.
## Settings & Configuration
You can access global settings through the **Config Panel**. Here you can:
- Adjust the **Polling Interval** for data updates.
- Toggle **Night Mode** or change the **Imagery Base Map** (e.g., Satellite, Terrain, Street).
- Manage **Cache Settings** to clear offline data.
---
> [!TIP]
> Use the **[Keyboard Shortcuts]** (coming soon) for faster navigation and panel toggling.
-32
View File
@@ -1,32 +0,0 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Build System
## Overview
WorldWideView uses a pnpm monorepo workspace for managing both the main application and its associated SDK and plugin packages. The primary build system relies on Next.js 16 with custom Webpack optimizations, specifically designed to output a standalone trace for highly efficient Docker containerization.
The core build configuration resides in `package.json` and `next.config.ts`. A custom standalone tracer strips unnecessary CLI dependencies (`prisma`, `dotenv`) from the final build to prevent fatal container runtime crashes.
## Build Workflows
### Standard Development
- **Install Dependencies:** `pnpm install` (Installs all workspace packages defined in `pnpm-workspace.yaml`).
- **Initial Setup:** `pnpm run setup` (Executes `scripts/setup.mjs` to generate a `.env.local` with a fresh `AUTH_SECRET`).
- **Run Development Server (All):** `pnpm dev:all` (Concurrently starts the Next.js frontend and the local `wwv-data-engine` backends).
### Production Build
- **Build Command:** `pnpm build` (Executes `next build --webpack`).
- **Output:** Generates a `.next/standalone/` folder ready for execution.
- **Static Assets:** `scripts/copy-cesium.mjs` is executed during `predev` and `build` to copy pre-compiled CesiumJS static assets into the `public/cesium/` directory, keeping them out of the output tracer.
## Platform Setup
- **Database Migrations:** Prisma schema is located at `prisma/schema.prisma`. During development, `pnpm dev` triggers a `predev` hook running `npx prisma migrate deploy` to ensure SQLite tables exist in `data/wwv.db`.
- **Microservices:** Data engine seeders and standalone Fastify backend plugins (like `wwv-plugin-iranwarlive/backend`) are started via `pnpm start:backends` and managed locally inside `packages/*/backend`.
- **Plugin Packages:** Internal plugin packages must be properly listed in `tsconfig.json` paths and `next.config.ts`'s `transpilePackages` array.
## Reference
- **Monorepo Config:** `pnpm-workspace.yaml` - defines package locations (`packages/*` and `packages/*/backend`).
- **Next Config:** `next.config.ts` - controls the standalone output, `transpilePackages`, and restrictive security headers.
- **Prisma Config:** `prisma.config.ts` - Native JavaScript object export used to bypass Next.js tracer issues with dynamic imports.
- **Cesium Script:** `scripts/copy-cesium.mjs` - Handles static asset injection.
+362
View File
@@ -0,0 +1,362 @@
# Creating a WorldWideView Plugin
This guide walks you through building, publishing, and listing your own WorldWideView plugin from scratch.
---
## Overview
WorldWideView plugins display geospatial data on a 3D Cesium globe. Every plugin must implement the `WorldPlugin` interface from the **Plugin SDK** (`@worldwideview/wwv-plugin-sdk`).
There are **three plugin formats**:
| Format | Use Case | Example |
|---|---|---|
| **`static`** | GeoJSON file loaded at startup — no API calls at runtime | Military Bases, Nuclear Facilities, Embassies |
| **`bundle`** | Full TypeScript class with custom logic, live API data, UI components | Aviation, Maritime, Wildfire |
| **`declarative`** | JSON-only manifest that points to an external API — no code needed | *(Future)* |
---
## Prerequisites
- Node.js ≥ 18
- pnpm (`npm install -g pnpm`)
- A npm account (for publishing to the npm registry)
- The WorldWideView monorepo cloned locally
---
## Step 1 — Create Your Plugin Package
All plugins live under `packages/` in the monorepo.
```bash
mkdir packages/wwv-plugin-my-data
cd packages/wwv-plugin-my-data
```
Create `package.json`:
```json
{
"name": "@worldwideview/wwv-plugin-my-data",
"version": "1.0.0",
"description": "WorldWideView plugin — my custom data layer",
"main": "src/index.ts",
"types": "src/index.ts",
"files": ["src"],
"keywords": [
"worldwideview",
"worldwideview-plugin",
"geojson",
"cesium",
"globe"
],
"repository": {
"type": "git",
"url": "https://github.com/silvertakana/worldwideview.git",
"directory": "packages/wwv-plugin-my-data"
},
"license": "ISC",
"author": "WorldWideView",
"peerDependencies": {
"@worldwideview/wwv-plugin-sdk": "*"
},
"worldwideview": {
"id": "my-data",
"icon": "MapPin",
"category": "Custom",
"format": "bundle"
}
}
```
> [!IMPORTANT]
> The `"worldwideview"` object block is strictly required if you intend to publish your plugin to the WorldWideView Marketplace. The marketplace uses this internal manifest to determine how to categorize and display your plugin automatically.
> * `id`: The unique string identifier.
> * `icon`: The Lucide React icon name (e.g. `MapPin`, `Satellite`, `Plane`).
> * `category`: Must match an existing category (e.g. `Aviation`, `Maritime`, `Natural Disaster`, `Custom`).
> * `format`: Either `bundle`, `static`, or `declarative`.
> [!IMPORTANT]
> The SDK is declared as a **peer dependency**, not a direct dependency. The host application provides it at runtime.
---
## Step 2 — Write Your Plugin Code
Create `src/index.ts`. Here are examples for the two most common formats:
### Option A — Static GeoJSON Plugin (simplest)
For static plugins, the npm package is just metadata. The actual loading is handled by the `StaticDataPlugin` loader at runtime, driven by a manifest + GeoJSON file.
```typescript
/**
* @worldwideview/wwv-plugin-my-data
*
* Static GeoJSON plugin — my custom dataset.
*
* This package exists for npm registry metadata. The actual plugin logic
* is handled by WorldWideView's StaticDataPlugin loader at runtime using
* the manifest + GeoJSON data file served from the host application.
*/
export const PLUGIN_ID = "my-data" as const;
```
For static plugins you also need:
1. A **GeoJSON file** placed at `public/data/my_data.geojson` in the main app
2. A **manifest entry** in the marketplace (see Step 4)
### Option B — Bundle Plugin (full control)
For bundle plugins, you write a class that implements the `WorldPlugin` interface:
```typescript
import type {
WorldPlugin,
GeoEntity,
TimeRange,
PluginContext,
LayerConfig,
CesiumEntityOptions,
} from "@worldwideview/wwv-plugin-sdk";
export class MyDataPlugin implements WorldPlugin {
// ─── Required Metadata ──────────────────────────────
id = "my-data";
name = "My Data Layer";
description = "Displays custom points on the globe.";
icon = "MapPin"; // Lucide icon name (string)
category = "custom" as const;
version = "1.0.0";
// ─── Lifecycle ──────────────────────────────────────
async initialize(ctx: PluginContext): Promise<void> {
// Called once when the plugin is loaded.
// Use ctx.apiBaseUrl, ctx.timeRange, ctx.onDataUpdate, etc.
}
destroy(): void {
// Called when the plugin is unloaded. Clean up timers, sockets, etc.
}
// ─── Data ───────────────────────────────────────────
async fetch(timeRange: TimeRange): Promise<GeoEntity[]> {
// Fetch your data from an API and return GeoEntity objects.
const res = await fetch("https://api.example.com/points");
const data = await res.json();
return data.map((item: any) => ({
id: String(item.id),
pluginId: this.id,
latitude: item.lat,
longitude: item.lon,
altitude: 0,
timestamp: new Date(),
label: item.name,
properties: { type: item.type },
}));
}
getPollingInterval(): number {
return 60_000; // Re-fetch every 60 seconds
}
// ─── Rendering ──────────────────────────────────────
getLayerConfig(): LayerConfig {
return {
color: "#3b82f6",
clusterEnabled: true,
clusterDistance: 40,
maxEntities: 5000,
};
}
renderEntity(entity: GeoEntity): CesiumEntityOptions {
return {
type: "point",
color: "#3b82f6",
size: 8,
};
}
}
```
---
## Step 3 — Publish to npm
```bash
cd packages/wwv-plugin-my-data
pnpm publish --access public
```
> [!NOTE]
> The marketplace pulls metadata (version, description, keywords, readme) directly from the npm registry. You do not need to duplicate this information anywhere else.
---
## Step 4 — Submit to the Marketplace
Once your package is published to npm, submit it for listing in the WorldWideView Marketplace:
1. Go to [marketplace.worldwideview.dev/submit](https://marketplace.worldwideview.dev/submit) (or open the Admin UI on a local marketplace instance)
2. Enter your **npm package name** (e.g. `@worldwideview/wwv-plugin-my-data`)
3. The marketplace automatically fetches your metadata from npm and reads the `"worldwideview"` block from your `package.json`
4. Your plugin enters a **pending** state for review
5. Once approved, it appears in the browse catalog
> [!IMPORTANT]
> The `"worldwideview"` block in your `package.json` is required for submission. Make sure `id`, `icon`, `category`, and `format` are correctly set before publishing.
### For static format plugins
If your plugin uses `"format": "static"`, your **GeoJSON file** must be hosted and accessible at a public URL, or included in the `public/data/` folder of the host WorldWideView application. The `dataFile` path in your manifest should point to that URL.
If you are contributing a plugin for inclusion in the official WorldWideView release, place the GeoJSON at `public/data/<name>.geojson` and open a pull request.
---
## Step 5 — Test Locally
1. Start all WorldWideView services: `pnpm run dev:all` (in the monorepo root)
2. (Wait for both the main app and marketplace to start)
3. Open the marketplace at `http://localhost:3001/browse`
4. Find your plugin and click **Install**
5. Verify the data appears on the globe at `http://localhost:3000`
---
## SDK Interface Reference
The `WorldPlugin` interface requires these properties and methods:
### Required Properties
| Property | Type | Description |
|---|---|---|
| `id` | `string` | Unique plugin identifier (e.g., `"my-data"`) |
| `name` | `string` | Display name shown in the sidebar |
| `description` | `string` | Short description |
| `icon` | `string \| ComponentType` | Lucide icon name or React component |
| `category` | `PluginCategory` | One of: `aviation`, `maritime`, `conflict`, `natural-disaster`, `infrastructure`, `cyber`, `economic`, `custom` |
| `version` | `string` | Semver version string |
### Required Methods
| Method | Returns | Description |
|---|---|---|
| `initialize(ctx)` | `Promise<void>` | Set up the plugin. Receives `PluginContext` with API URLs, time range, callbacks |
| `destroy()` | `void` | Clean up resources (timers, sockets, etc.) |
| `fetch(timeRange)` | `Promise<GeoEntity[]>` | Return the data to display on the globe |
| `getPollingInterval()` | `number` | Milliseconds between `fetch()` calls |
| `getLayerConfig()` | `LayerConfig` | Layer appearance (color, clustering, limits) |
| `renderEntity(entity)` | `CesiumEntityOptions` | How each entity renders on the globe |
### Optional Methods
| Method | Returns | Description |
|---|---|---|
| `getSelectionBehavior(entity)` | `SelectionBehavior \| null` | Trail / fly-to on click |
| `getServerConfig()` | `ServerPluginConfig` | Server-side API routing |
| `getFilterDefinitions()` | `FilterDefinition[]` | Declarative filter UI |
| `getSidebarComponent()` | `ComponentType` | Custom sidebar panel |
| `getDetailComponent()` | `ComponentType<{ entity }>` | Custom detail panel |
| `getSettingsComponent()` | `ComponentType<{ pluginId }>` | Custom settings panel |
### Key Types
```typescript
interface GeoEntity {
id: string;
pluginId: string;
latitude: number;
longitude: number;
altitude?: number;
heading?: number;
speed?: number;
timestamp: Date;
label?: string;
properties: Record<string, unknown>;
}
interface LayerConfig {
color: string;
iconUrl?: string;
clusterEnabled: boolean;
clusterDistance: number;
minZoomLevel?: number;
maxEntities?: number;
}
interface CesiumEntityOptions {
type: "billboard" | "point" | "polyline" | "polygon" | "label" | "model";
color?: string;
size?: number;
iconUrl?: string;
rotation?: number;
modelUrl?: string;
modelScale?: number;
// ... more options
}
```
---
## Real Examples
### Borders Plugin (bundle format)
A minimal bundle plugin that implements the `WorldPlugin` interface directly:
- **Source**: `packages/wwv-plugin-borders/src/index.ts`
- **npm**: `@worldwideview/wwv-plugin-borders`
### Military Bases Plugin (static format)
A static GeoJSON plugin where the npm package is just metadata:
- **Source**: `packages/wwv-plugin-military-bases/src/index.ts`
- **GeoJSON**: `public/data/military_bases.geojson`
- **npm**: `@worldwideview/wwv-plugin-military-bases`
- **Manifest**: Defined in `worldwideview-marketplace/src/data/pluginManifests.ts`
---
## How It All Connects
```
Developer writes plugin
│
▼
Publish to npm ► npm registry (stores version, description, keywords, readme)
│
▼
Submit npm package name to Marketplace
│
▼
Marketplace fetches metadata from npm ← npm registry
and reads the "worldwideview" block from package.json
│
▼
Review → Plugin appears in browse catalog
│
▼
User clicks "Install"
│
▼
Marketplace sends manifest to WorldWideView instance
│
▼
Plugin saved to database (Prisma) → loaded on next startup
│
▼
loadPluginFromManifest() routes by format:
static → StaticDataPlugin (GeoJSON loader)
bundle → dynamic import()
│
▼
Plugin renders on the 3D globe
```
-34
View File
@@ -1,34 +0,0 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Deployment
## Overview
WorldWideView utilizes a containerized deployment strategy based on Docker's multi-stage builds. To minimize the footprint of the Next.js runtime, it leverages the Next.js `standalone` output trace, effectively dropping unnecessary development dependencies and generating a highly optimized Node.js artifact.
## Package Types
### Main Application
- **Build Output:** Located at `.next/standalone/`.
- **Static Assets:** Cesium static workers are injected at build time via `scripts/copy-cesium.mjs`.
### Plugin Microservices
- Standalone plugin backends (e.g., `wwv-plugin-iranwarlive/backend`) are isolated via individual `Dockerfile` configurations and orchestrated together in production using `docker-compose.yml`.
## Platform Deployment
### Coolify Integration
WorldWideView deploys optimally to Coolify using a Dockerfile builder.
- **Environment Variables:** Must be explicitly mapped in the Coolify UI (e.g., `DATABASE_URL`, `AUTH_SECRET`).
- **Persistent Storage:** SQLite requires a persistent volume mounted to `/app/data` to ensure the frontend registry (installed plugins, user configs) survives container rebuilds.
- **Microservices Deployment:** The `wwv-data-engine-internal` and associated plugin seeders are deployed as separate Coolify services communicating over private internal networks.
### Docker Structure
- **Dockerfile:** Found at the project root (`Dockerfile`). Uses an Extractor Pattern (`deps` → `builder` → `runner`). The `.git` and `node_modules` folders must be explicitly untracked to prevent cache overlap.
- **Compose:** Local multi-container emulation is handled via `docker-compose.yml`.
## Reference
- **Standalone Config:** `next.config.ts` (sets `output: "standalone"`).
- **Prisma Export:** `prisma.config.ts` ensures no CLI wrappers are invoked inside the standalone container, preventing fatal `MODULE_NOT_FOUND` runtime crashes.
- **Docker Mounts:**
- Main App: `/app/data` (SQLite DB)
- Data Engine: `/app/packages/wwv-data-engine/data` (SQLite DB)
- Cache: `/data` (Redis)
-73
View File
@@ -1,73 +0,0 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Development
## Overview
Development on WorldWideView prioritizes modularity, high performance, and strict architectural boundaries between the UI and the 3D rendering context. We adhere to rigorous file size constraints and rely heavily on Vanilla CSS and Zustand slice-patterns to maintain clarity across the large ecosystem.
## Code Style
### File Size Limits
- **Max 150 lines per file.** If a component or function grows beyond this, you must modularize it. Extract helper functions, split React components, and utilize custom hooks.
### Styling Conventions
- **Vanilla CSS Only:** Do not use Tailwind CSS or CSS-in-JS.
- **Global Styles:** Located at `src/app/globals.css`.
- **Component Styles:** Use CSS Modules (`.module.css`) or co-locate `.css` files directly next to their components.
- **HUD Animations:** Specialized interface animations are stored in `src/styles/hud-animations.css`.
### Import Aliases
- Application core: `@/*` → `./src/*`
- Plugin SDK: `@worldwideview/wwv-plugin-sdk` → `./packages/wwv-plugin-sdk/src`
- Custom plugins use their respective names configured in `tsconfig.json`.
## Common Patterns
### Entity Rendering
When translating raw plugin data into `CesiumEntityOptions` inside `renderEntity()`, follow these strict graphical rules:
```typescript
// Correct Point Pattern
renderEntity(entity: GeoEntity): CesiumEntityOptions {
return {
type: "point",
color: "#ff0000",
size: 10,
outlineColor: "#ffffff",
outlineWidth: 2
};
}
// Correct Billboard Pattern
renderEntity(entity: GeoEntity): CesiumEntityOptions {
return {
type: "billboard",
color: "#ffffff",
iconUrl: "/icons/aircraft.png",
iconScale: 0.5
};
}
```
> [!WARNING]
> **NEVER MIX PROPERTIES:** Do not apply `size`, `outlineWidth`, or `outlineColor` to a `billboard` entity. Mixing these parameters causes severe GPU clipping and rendering artifacts in Cesium.
### State Access
Zustand is divided into slices. For performance, components must select exactly the properties they need to avoid over-rendering:
```typescript
// From src/components/panels/LayerPanel.tsx
const activeLayers = useStore((state) => state.layers.active);
const toggleLayer = useStore((state) => state.layers.toggle);
```
## Workflows
### Debugging & Temporary Scripts
Whenever generating temporary debugging scripts, testing REST endpoints via `.mjs`, or dumping traces/JSON outputs, **save these exclusively inside `/local-scripts/`**.
- *Reference:* The root directory is strictly for production configuration files.
### Scaffold a New Component
1. Create a new directory under `src/components/{category}/MyComponent`.
2. Add `MyComponent.tsx` and `MyComponent.module.css`.
3. Export from a local `index.ts` if creating a composite view.
## Reference
- **Core Abstractions:** See `packages/wwv-plugin-sdk/src/PluginTypes.ts` for interface expectations.
- **State Slices:** Located in `src/core/state/` (e.g., `globeSlice.ts`, `dataSlice.ts`).
-33
View File
@@ -1,33 +0,0 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Files Catalog
## Overview
WorldWideView is structured as a pnpm monorepo. The primary application resides in the root `src/` directory, while external dependencies, plugins, and the core Plugin SDK are abstracted into the `packages/` directory.
The system is highly modularized to separate React UI rendering from heavy CesiumJS 3D operations and high-frequency real-time WebSocket state management.
## Core Source Files
- `src/app/` - The Next.js App Router entry points. Contains `layout.tsx` (the core React shell), `page.tsx` (the globe view), and `/api/` (server-side NextAuth and API handlers).
- `src/core/plugins/PluginManager.ts` - Central orchestration unit for dynamic plugins. Handles loading, lifecycle (`initialize`, `destroy`), and manifest resolution.
- `src/core/globe/GlobeView.tsx` - The primary CesiumJS container. It memoizes Zustand state to prevent heavy re-renders while injecting `EntityRenderer` primitives.
- `src/core/data/DataBus.ts` - Singleton pub/sub event bus handling all high-velocity WebSocket stream events without triggering React re-renders.
- `src/core/state/store.ts` - The primary Zustand state registry exporting all nine discrete slices (`globe`, `layers`, `timeline`, `ui`, `filter`, `data`, `config`, `favorites`, `geojson`).
## Platform Implementation
- `src/core/plugins/loaders/InstalledPluginsLoader.ts` - Platform-specific loader that dynamically injects ES module CDNs via `import(/* webpackIgnore: true */)`.
- `src/core/globe/hooks/useCameraActions.ts` - Abstraction connecting React UI logic to raw CesiumJS camera math (flyTo, lookAt).
- `src/lib/edition.ts` - Platform edition configuration. Exposes runtime feature flags for `local`, `cloud`, and `demo` deployments.
## Build System
- `package.json` - Root monorepo configuration with `pnpm` workspace bindings.
- `next.config.ts` - Next.js compiler settings, security headers, and standalone output configuration.
- `docker-compose.yml` - Defines the orchestration of the frontend, Redis cache, and all local plugin microservice backends (`wwv-data-engine`).
## Configuration
- `prisma/schema.prisma` - Local SQLite and cloud PostgreSQL database schema for storing user settings and installed plugin manifests.
- `scripts/copy-cesium.mjs` - Crucial build-time script that extracts and copies CesiumJS static web workers to `public/cesium/`.
- `public/` - Static assets, plugin icons, and compiled Cesium workers.
## Reference
- **Plugins Directory:** All plugins conform to the `@worldwideview/wwv-plugin-sdk` interface and are developed inside `packages/wwv-plugin-<name>/`.
- **Microservices Directory:** Standalone Fastify backends are nested within `packages/wwv-plugin-<name>/backend/`.
-328
View File
@@ -1,328 +0,0 @@
<!-- Generated: 2026-04-23 20:29:00 UTC -->
# End-to-End Tutorial: Building a Real-Time ISS Tracking Plugin
Welcome! This tutorial is designed for complete beginners. If you have never built a WorldWideView plugin before, you are in the right place.
By following these steps exactly, you will build a complete, real-time International Space Station (ISS) tracker from scratch. You will learn how to set up your environment, stream live data using a backend seeder, render it in 3D on the globe, and publish your work to the world.
Let's get started.
---
## Step 1: Setting up your Workspace
Before we write any code, we need to prepare your computer. We will install the required tools and download the two main repositories that make up the WorldWideView platform.
### 1.1 Install Prerequisites
Ensure you have the following installed on your machine:
1. **Node.js**: Download and install [Node.js](https://nodejs.org/) (Version 18 or higher is required).
2. **Git**: Download and install [Git](https://git-scm.com/).
3. **pnpm**: This is the package manager we use. Open your terminal and run:
```bash
npm install -g pnpm
```
### 1.2 Clone the Repositories
You need both the frontend application and the backend data engine. Open your terminal and navigate to the folder where you want to store your code (e.g., `C:\dev`).
Run these commands to download the code:
```bash
git clone https://github.com/silvertakana/worldwideview.git
git clone https://github.com/silvertakana/wwv-data-engine.git
```
### 1.3 Install Dependencies
Next, we need to install the libraries that these projects depend on.
First, install dependencies for the Data Engine:
```bash
cd wwv-data-engine
pnpm install
```
Second, install dependencies for the main WorldWideView application:
```bash
cd ../worldwideview
pnpm install
```
### 1.4 Setup Environment Variables
WorldWideView needs a few basic configuration keys to run.
While still in the `worldwideview` folder, run the automated setup script. This will generate a `.env.local` file with the necessary secrets:
```bash
pnpm run setup
```
Your workspace is now ready!
---
## Step 2: Creating the Data Engine Seeder (Backend)
The ISS moves incredibly fast. If our frontend tries to ask for its location every second, it will lag. Instead, we use the **Bring Your Own Backend (BYOB)** pattern. We will write a "Seeder" script in the Data Engine that fetches the ISS location and instantly broadcasts it to the frontend via WebSockets.
### 2.1 Create the Seeder File
Navigate to your data engine repository and create a new file named `iss.ts` in the `src/seeders` folder:
`c:\dev\wwv-data-engine\src\seeders\iss.ts`
### 2.2 Write the Polling Logic
Open `iss.ts` in your text editor and paste the following code. This script reaches out to the free WhereTheISS.at API every 5 seconds and saves the data to the engine's memory (Redis).
```typescript
import { setLiveSnapshot } from '../core/redis';
import axios from 'axios';
const WTIA_URL = 'https://api.wheretheiss.at/v1/satellites/25544';
const POLLING_INTERVAL = 5000; // 5 seconds
async function pollISS() {
try {
// 1. Fetch data from the API
const response = await axios.get(WTIA_URL);
const data = response.data;
// 2. Format the data into a GeoEntity object
const stateObj = {
id: 25544,
name: "International Space Station",
latitude: data.latitude,
longitude: data.longitude,
altitude: data.altitude * 1000, // Convert kilometers to meters
velocity: data.velocity,
visibility: data.visibility,
footprint: data.footprint
};
// 3. Save to Redis under the 'iss' namespace for 60 seconds
await setLiveSnapshot('iss', { "25544": stateObj }, 60);
console.log(`[ISS] Poll OK: updated position to ${data.latitude}, ${data.longitude}`);
} catch (error) {
console.error(`[ISS] Polling error:`, error.message);
} finally {
// 4. Repeat the process after 5 seconds
setTimeout(pollISS, POLLING_INTERVAL);
}
}
// Start the loop
pollISS();
```
### 2.3 Register the Seeder
The engine needs to know your seeder exists. Open `c:\dev\wwv-data-engine\src\seeders\index.ts` and add this line at the bottom:
```typescript
import './iss';
```
---
## Step 3: Testing the Data Engine
Before we build the frontend, let's prove that our backend is actually fetching the ISS data.
### 3.1 Start the Engine
In your terminal, navigate to the `wwv-data-engine` folder and start the backend:
```bash
pnpm dev:backends
```
You should see `[ISS] Poll OK: updated position` appearing in your console every 5 seconds. Leave this terminal running.
### 3.2 Write a Quick Test Script
Open a *new* terminal window. Let's write a tiny script to peek into the engine's memory. Create a file called `test_iss.mjs` in the `wwv-data-engine` folder:
```javascript
// test_iss.mjs
import Redis from 'ioredis';
const redis = new Redis();
async function verify() {
const data = await redis.get('data:iss:live');
if (data) {
console.log("Success! We found the ISS:", JSON.parse(data));
} else {
console.log("No data found yet.");
}
process.exit(0);
}
verify();
```
Run the script:
```bash
node test_iss.mjs
```
If you see a large block of data containing coordinates and altitude, your backend is working perfectly!
---
## Step 4: Creating the WorldWideView Plugin (Frontend)
Now we will build the visual part of the plugin that connects to our backend stream and draws the ISS on the 3D globe.
### 4.1 Scaffold the Plugin
In your terminal, navigate back to your main `c:\dev` folder. We will use the official CLI tool to generate a blank plugin template. Run:
```bash
npx @worldwideview/create-plugin@latest wwv-plugin-iss
```
When prompted, name the folder `wwv-plugin-iss`.
Move into your new plugin folder and install its dependencies:
```bash
cd wwv-plugin-iss
npm install
```
### 4.2 Write the Plugin Logic
Open `c:\dev\wwv-plugin-iss\src\index.ts` in your text editor. Replace everything in the file with this code:
```typescript
import type { WorldPlugin, GeoEntity, PluginContext, LayerConfig, CesiumEntityOptions } from "@worldwideview/wwv-plugin-sdk";
export class IssPlugin implements WorldPlugin {
// The ID MUST match the namespace we used in the backend ('iss')
id = "iss";
name = "ISS Live Tracker";
description = "Real-time International Space Station tracking.";
icon = "Satellite";
category = "space" as const;
version = "1.0.0";
async initialize(ctx: PluginContext): Promise<void> {
console.log("ISS Plugin loaded!");
}
destroy(): void { }
async fetch(): Promise<GeoEntity[]> {
// We return an empty array because the WebSockets handle the data automatically.
return [];
}
getPollingInterval(): number {
return 0; // Disabled: we use continuous WebSockets instead of polling.
}
getLayerConfig(): LayerConfig {
return {
color: "#00ffcc",
clusterEnabled: false
};
}
renderEntity(entity: GeoEntity): CesiumEntityOptions {
// Level of Detail (LOD): Use a 2D billboard from far away,
// and transition to a 3D model when zooming in close.
return {
type: "billboard",
color: "#ffffff",
iconUrl: "https://unpkg.com/wwv-plugin-iss/assets/iss-icon.png",
iconScale: 0.8,
modelUrl: "https://unpkg.com/wwv-plugin-iss/assets/ISS_stationary.glb",
modelScale: 2.5,
heading: entity.heading || 0,
};
}
}
```
---
## Step 5: Connecting and Testing Everything
Now we will link your new plugin to your local WorldWideView application to see it in action.
### 5.1 Link the Plugin
In your `wwv-plugin-iss` terminal, tell the CLI where your main WorldWideView folder is:
```bash
npx wwv config set wwv-path C:\dev\worldwideview
```
Now, link the plugin. This creates a shortcut so WorldWideView can see your code:
```bash
npm run link
```
Start the plugin watcher. This will automatically update your plugin if you make any changes to the code:
```bash
npm run dev
```
Leave this terminal running.
### 5.2 Start WorldWideView
Open a third, final terminal window. Navigate to your main `worldwideview` folder and start the frontend application:
```bash
cd C:\dev\worldwideview
pnpm dev
```
### 5.3 View the ISS
1. Open your web browser and go to `http://localhost:3000`.
2. Click the **Layers** icon on the left sidebar.
3. Find **ISS Live Tracker** in the list and toggle it ON.
4. The globe will instantly fly to the current location of the ISS, and you will see it moving in real-time!
> [!TIP]
> **Troubleshooting missing points:**
> - Ensure your Data Engine terminal (`pnpm dev:backends`) is still running.
> - Press `F12` in your browser to open Developer Tools. Check the `Console` tab for any red errors.
> - Ensure the `id` in your plugin (`"iss"`) exactly matches the name you used in the backend `setLiveSnapshot('iss', ...)`.
---
## Step 6: Publishing Your Plugin
You've built it, now share it with the world!
### 6.1 Update package.json
Open `c:\dev\wwv-plugin-iss\package.json`. You must add a `"worldwideview"` metadata block so the marketplace knows how to read your plugin. Ensure your file looks like this:
```json
{
"name": "wwv-plugin-iss",
"version": "1.0.0",
"main": "dist/index.js",
"worldwideview": {
"id": "iss",
"name": "ISS Live Tracker",
"version": "1.0.0",
"icon": "Satellite",
"category": "space"
},
"scripts": { ... }
}
```
### 6.2 Publish to NPM
In your plugin terminal, log in to NPM and publish your package:
```bash
npm login
npm publish --access public
```
### 6.3 Submit to the Marketplace
1. Go to the official marketplace at `https://marketplace.worldwideview.dev/submit`.
2. Type in your package name (`wwv-plugin-iss`) and click submit.
3. The system will automatically verify your code. Once approved, any WorldWideView user on the planet can click "Install" to add your ISS tracker to their globe.
**Congratulations!** You have successfully navigated the entire stack, from API polling and WebSockets to 3D rendering and global publishing.
-80
View File
@@ -1,80 +0,0 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Advanced Plugin Guide
This guide covers complex architectures, real-time telemetry streaming, and the deployment lifecycle for WorldWideView plugins. If you haven't built a basic plugin yet, start with the **[Quickstart](plugin-quickstart.md)**.
## Architecture Paradigm: The All-Bundle Model
WorldWideView operates on a strict **Dynamic CDN Loaded (Bundle)** architecture.
> [!WARNING]
> **Deprecation Notice:** The legacy `StaticDataPlugin` (GeoJSON loaders) and `DeclarativePlugin` runtimes are fully deprecated. All new plugins must be dynamically imported at runtime as ES module bundles via `import(/* webpackIgnore: true */ entry)`.
### How Plugins Load
1. A user clicks "Install" in the **Marketplace**.
2. The marketplace sends the plugin manifest (containing an ES Module CDN URL, like `unpkg.com`) to the WorldWideView database.
3. At runtime, the `InstalledPluginsLoader` dynamically fetches the JavaScript bundle.
4. The plugin is instantiated, and its `initialize(ctx)` method is invoked.
## Real-Time Data: Bring Your Own Backend (BYOB)
Relying on the frontend `fetch()` method is insufficient for high-frequency real-time tracking (like aviation or maritime). For continuous telemetry, you must build a **Data Engine Seeder** — a containerized backend microservice.
### Microservice Seeder Architecture
Instead of the frontend fetching data, your backend container connects to an upstream source, normalizes the data, and publishes it to the central Redis stream managed by `wwv-data-engine`.
1. **Scaffold a Backend:** Use the CLI to generate a backend template.
```bash
npx @worldwideview/cli create-backend my-plugin-backend
```
2. **Containerize:** This generates a Fastify Node.js server with a `Dockerfile` and `docker-compose.yml`.
3. **Publish to Redis:** Your backend polls the external API (e.g., ADS-B Exchange) and pushes snapshots to the WorldWideView Redis pipeline.
4. **WebSocket Delivery:** The central `wwv-data-engine` immediately broadcasts these updates over WebSockets to all connected clients.
> [!TIP]
> **Debugging WebSockets:** If your frontend isn't receiving data from your backend seeder:
> 1. Check the `wwv-data-engine` logs to ensure your seeder is publishing to Redis successfully.
> 2. Verify the frontend is connected to the correct WebSocket endpoint. Local instances default to `ws://localhost:5001/stream`, while unrecognized seeders fall back to the cloud at `wss://dataengine.worldwideview.dev/stream`.
## Advanced Cesium Rendering
When returning `CesiumEntityOptions` in `renderEntity(entity)`, you have direct access to the 3D engine's capabilities.
### 3D Models vs. Billboards (LOD Strategy)
To maintain 60 FPS with tens of thousands of entities, use WorldWideView's Level of Detail (LOD) promotion system.
- Render distant entities as simple `billboard` or `point` primitives.
- When the camera gets close, the system's `useModelRendering` hook can promote the entity to a full 3D glTF model.
```typescript
renderEntity(entity: GeoEntity): CesiumEntityOptions {
return {
type: "billboard", // Primary lightweight renderer
color: "#ffffff",
iconUrl: "https://unpkg.com/my-plugin/assets/icon.png",
iconScale: 0.5,
// Provide a 3D model URL. The engine will swap it in automatically at close range.
modelUrl: "https://unpkg.com/my-plugin/assets/model.glb",
modelScale: 1.0,
heading: entity.heading,
};
}
```
> [!CAUTION]
> **GPU Clipping Bug:** NEVER mix `size`, `outlineWidth`, or `outlineColor` properties onto an entity of `type: "billboard"`. This will cause the WebGL compiler to panic and result in severe visual clipping artifacts.
## Publishing to the Marketplace
To distribute your plugin globally:
1. **Publish to NPM:**
```bash
npm publish --access public
```
2. **Submit:** Navigate to `https://marketplace.worldwideview.dev/submit`.
3. **Register:** Enter your NPM package name. The marketplace automatically scrapes your `package.json` for the required `"worldwideview"` object block (containing your `id`, `icon`, and `category`).
4. **Review:** Once approved, your plugin's ES Module bundle will be served via CDN to all WorldWideView instances worldwide.
### Debugging Marketplace Submissions
- **"Invalid Manifest" Error:** Ensure you are using `@worldwideview/wwv-plugin-sdk` as a `peerDependency` (not a direct dependency) so the host application injects the context correctly.
- **Icon Not Showing:** Icons must be valid Lucide icon strings (e.g., `"Plane"`, `"Anchor"`).
-126
View File
@@ -1,126 +0,0 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Quickstart: Creating Your First Plugin
Welcome to WorldWideView plugin development! This tutorial will guide you through creating your first custom data layer on the 3D globe.
By the end of this guide, you will have a working plugin that plots real-time data on the WorldWideView map.
## 1. Prerequisites
Before you start, ensure you have:
- Node.js ≥ 18
- `npm` or `pnpm` installed
- A running instance of WorldWideView on your local machine (running at `http://localhost:3000`).
## 2. Scaffold Your Plugin
WorldWideView plugins are built as standard NPM packages. They are entirely decoupled from the core application, allowing you to develop and publish them independently.
To generate a new plugin template, use the official CLI:
```bash
npx @worldwideview/create-plugin@latest my-first-plugin
cd my-first-plugin
npm install
```
This creates a lightweight Vite-based project pre-configured with the `@worldwideview/wwv-plugin-sdk`.
## 3. Link Your Plugin to WorldWideView
To see your plugin live on the globe while you develop, you need to link it to your local WorldWideView instance.
First, tell the CLI where your WorldWideView repository is located:
```bash
npx wwv config set wwv-path C:\path\to\your\worldwideview
```
Next, link the plugin. This creates a symlink so your local WorldWideView instance can dynamically load your code:
```bash
npm run link
```
Finally, start the plugin watcher. This will automatically rebuild your plugin whenever you save a file:
```bash
npm run dev
```
> [!TIP]
> **Debugging Link Issues:** If your plugin doesn't appear in the WorldWideView "Installed Plugins" list after linking, check your `package.json`. The `"worldwideview"` object block is strictly required. Ensure `id`, `name`, and `version` are populated correctly.
## 4. Explore the Code
Open `src/index.ts` in your text editor. You'll see a class that implements the `WorldPlugin` interface:
```typescript
import type { WorldPlugin, GeoEntity, PluginContext, LayerConfig, CesiumEntityOptions } from "@worldwideview/wwv-plugin-sdk";
export class MyFirstPlugin implements WorldPlugin {
id = "my-first-plugin";
name = "My First Data Layer";
description = "A simple example plugin.";
icon = "MapPin";
category = "custom" as const;
version = "1.0.0";
async initialize(ctx: PluginContext): Promise<void> {
console.log("Plugin initialized!");
}
destroy(): void { }
async fetch(timeRange: TimeRange): Promise<GeoEntity[]> {
// Generate a single dummy point over Paris
return [{
id: "test-point-1",
pluginId: this.id,
latitude: 48.8566,
longitude: 2.3522,
timestamp: new Date(),
properties: { name: "Hello World" },
}];
}
getPollingInterval(): number {
return 60_000; // Fetch every 60 seconds
}
getLayerConfig(): LayerConfig {
return {
color: "#ff0000",
clusterEnabled: false,
clusterDistance: 40,
};
}
renderEntity(entity: GeoEntity): CesiumEntityOptions {
return {
type: "point",
color: "#ff0000",
size: 15,
outlineColor: "#ffffff",
outlineWidth: 2
};
}
}
```
## 5. View Your Plugin
1. Ensure your WorldWideView main application is running (`pnpm dev` or `pnpm dev:all` in the main repo).
2. Open your browser to `http://localhost:3000`.
3. Open the **Layers** panel on the left sidebar.
4. Locate "My First Data Layer" and toggle it on.
5. The globe will fly to Paris, and you should see a red dot!
> [!WARNING]
> **Debugging Missing Points:** If the layer is toggled on but you don't see the point:
> 1. Check your browser's Developer Console (F12) for any `DataBus` errors.
> 2. Ensure your `fetch()` method returns an array of `GeoEntity` objects with valid `latitude` and `longitude` properties.
> 3. Verify that your `renderEntity()` function returns a valid type (`point`, `billboard`, etc.).
## Next Steps
Congratulations! You've successfully built and linked your first plugin.
For advanced features—like real-time WebSocket streaming, containerizing your own backend microservices, or publishing your plugin to the global Marketplace—proceed to the **[Advanced Plugin Guide](docs/plugin-advanced.md)**.
-28
View File
@@ -1,28 +0,0 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Project Overview
WorldWideView is a real-time geospatial intelligence engine that visualizes live global data on an interactive 3D globe. It leverages a modern frontend stack to render high-density datasets synchronously, including aircraft, maritime vessels, conflict events, satellites, and environmental data.
The core value proposition of WorldWideView is mapping diverse, decoupled intelligence streams onto a central geographic interface using a dynamically loaded plugin architecture. Data sources operate completely decoupled from the display platform, streaming observations via WebSockets for sub-second visual updates. The ecosystem consists of multiple repositories, including the main app (`worldwideview`), the plugin marketplace (`worldwideview-marketplace`), and the WebSocket push server (`wwv-data-engine`).
## Key Files
- `package.json` (Lines 1-76) - Core dependencies and project metadata for the monorepo workspace.
- `src/app/layout.tsx` - Global application shell and React structure.
- `src/core/plugins/PluginManager.ts` - Heart of the engine, registers and lifecycle-manages external intelligence views.
- `src/core/globe/GlobeView.tsx` - Main Cesium globe component rendering.
## Technology Stack
- **Framework:** Next.js 16 (App Router) — `src/app/`
- **Language:** TypeScript 5 (Strict Mode) — `tsconfig.json`
- **3D Engine:** CesiumJS + Resium (Google Photorealistic 3D Tiles) — `src/core/globe/GlobeView.tsx`
- **State Management:** Zustand — `src/core/state/` (slice-based store)
- **Event Bus:** Custom typed `DataBus` — `src/core/data/DataBus.ts`
- **Database:** SQLite via Prisma (local), PostgreSQL (cloud) — `prisma/schema.prisma`
- **Styling:** Vanilla CSS (no Tailwind) — `src/app/globals.css`
## Platform Support
Built as a highly portable Next.js container, it supports multiple deployment profiles controlled by `NEXT_PUBLIC_WWV_EDITION` (default: `local`).
- **Local (`local`)**: Self-hosted, full features, auth enabled.
- **Cloud (`cloud`)**: Managed cloud instance, full features.
- **Demo (`demo`)**: Public demo, auth disabled, optional admin via `WWV_DEMO_ADMIN_SECRET`.
Feature flags are evaluated at runtime in `src/core/edition.ts`.
@@ -1,145 +0,0 @@
# Expand OSM Chips Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Expand the available OSM search chips to include a curated list of ~30 pre-loaded OSINT-relevant tags, and add a live Taginfo API autocomplete search to dynamically find and select any of the millions of other OSM tags.
**Architecture:** We will replace the current small `COMMON_TAGS` array with a richer, categorized list inside the `OSMSidebar` file. To allow access to "all" tags without crashing the UI, we will add a debounced fetch hook that hits `https://taginfo.openstreetmap.org/api/4/tags/popular` (or the equivalent search endpoint) when the user types in the filter box. These dynamically fetched tags will temporarily populate the chip list.
**Tech Stack:** React, TypeScript, Taginfo API
---
### Task 1: Update Pre-Loaded COMMON_TAGS
**Files:**
- Modify: `c:\dev\worldwideview\packages\wwv-plugin-osm-search\src\components\OSMSidebar.tsx:6-11`
- [ ] **Step 1: Replace existing COMMON_TAGS array**
```tsx
const COMMON_TAGS = [
// Military & Security
"military=base", "military=bunker", "amenity=police", "amenity=prison",
// Aviation & Maritime
"aeroway=aerodrome", "aeroway=helipad", "aeroway=hangar", "man_made=pier", "harbour=yes",
// Infrastructure & Utilities
"power=plant", "power=substation", "telecom=antenna", "man_made=communications_tower", "man_made=water_tower",
// Transport
"highway=bus_stop", "railway=station", "amenity=fuel", "amenity=parking",
// Medical & Emergency
"amenity=hospital", "amenity=fire_station", "amenity=clinic",
// General Commercial & Industrial
"shop=supermarket", "tourism=hotel", "industrial=factory", "landuse=industrial",
// Education & Amenities
"amenity=school", "amenity=university", "amenity=cafe", "building=house"
];
```
- [ ] **Step 2: Commit**
```bash
git add packages/wwv-plugin-osm-search/src/components/OSMSidebar.tsx
git commit -m "feat(osm-search): expand quick preset tags with OSINT categories"
```
### Task 2: Implement Taginfo Dynamic Autocomplete
**Files:**
- Modify: `c:\dev\worldwideview\packages\wwv-plugin-osm-search\src\components\OSMSidebar.tsx`
- [ ] **Step 1: Add state and debounced fetch logic inside OSMSidebar component**
```tsx
const [searchText, setSearchText] = useState("");
const [activeTags, setActiveTags] = useState<string[]>([]);
const [dynamicTags, setDynamicTags] = useState<string[]>([]);
const [isSearchingApi, setIsSearchingApi] = useState(false);
// Add this useEffect below the useState hooks
React.useEffect(() => {
if (searchText.length < 3) {
setDynamicTags([]);
return;
}
const timer = setTimeout(async () => {
setIsSearchingApi(true);
try {
// Fetch tags matching the search term from OSM Taginfo
const res = await fetch(`https://taginfo.openstreetmap.org/api/4/search/by_keyword?query=${encodeURIComponent(searchText)}`);
const data = await res.json();
if (data && data.data) {
// Extract exact key=value pairs or just keys, format as "key=value"
const tags = data.data
.filter((item: any) => item.key && item.value)
.map((item: any) => `${item.key}=${item.value}`)
.slice(0, 15); // Limit to top 15 results
setDynamicTags(tags);
}
} catch (err) {
console.error("Taginfo fetch failed", err);
} finally {
setIsSearchingApi(false);
}
}, 500); // 500ms debounce
return () => clearTimeout(timer);
}, [searchText]);
```
- [ ] **Step 2: Update rendering logic to merge static and dynamic tags**
Look for the `renderedTags` definition and replace it:
```tsx
// Combine filtered common tags with newly fetched dynamic tags, removing duplicates
const filteredCommon = searchText
? COMMON_TAGS.filter(t => t.toLowerCase().includes(searchText.toLowerCase()))
: COMMON_TAGS;
const renderedTags = Array.from(new Set([...filteredCommon, ...dynamicTags]));
```
- [ ] **Step 3: Add loading indicator to the search input area**
Look for the `<input>` element for `searchText` and wrap it/add a loading indicator:
```tsx
<div style={{ position: "relative" }}>
<input
style={{
width: "100%",
padding: "8px",
paddingRight: "24px",
backgroundColor: "rgba(0,0,0,0.3)",
color: "#fff",
border: "1px solid var(--border-subtle)",
borderRadius: "4px",
fontSize: "13px"
}}
placeholder="Filter or search OSM for tags..."
value={searchText}
onChange={e => setSearchText(e.target.value)}
/>
{isSearchingApi && (
<span style={{
position: "absolute",
right: "8px",
top: "50%",
transform: "translateY(-50%)",
fontSize: "10px",
color: "var(--text-muted)"
}}>
⏳
</span>
)}
</div>
```
- [ ] **Step 4: Commit**
```bash
git add packages/wwv-plugin-osm-search/src/components/OSMSidebar.tsx
git commit -m "feat(osm-search): add live Taginfo autocomplete for unlisted tags"
```
@@ -1,139 +0,0 @@
# Plugin Versioning Streamlining Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Refactor all WorldWideView plugin classes to derive their `version` property dynamically from their local `package.json` file rather than hardcoding string literals.
**Architecture:** We will replace the hardcoded `version = "x.y.z"` strings in the core `WorldPlugin` interface implementations across all monorepo packages. We will utilize TypeScript's JSON module resolution feature to `import pkg from "../package.json"` and map `version = pkg.version`. This ensures that `pnpm version patch` is the single source of truth and eliminates the double-bookkeeping that previously made CI fixes tedious.
**Tech Stack:** TypeScript, Next.js / bundler (JSON module resolution), pnpm workspaces.
---
## Task 1: Verify TypeScript Configuration
**Files:**
- Modify: N/A (Verification step)
- [ ] **Step 1: Check `tsconfig.json` for JSON resolution**
Run: `cat tsconfig.json | grep resolveJsonModule`
Expected: `"resolveJsonModule": true`
- [ ] **Step 2: Check compiler compatibility**
Run: `pnpm exec tsc --noEmit`
Expected: PASS (exit code 0)
## Task 2: Refactor Group A Plugins (Core Infrastructure)
**Files:**
- Modify: `packages/wwv-plugin-aviation/src/index.ts`
- Modify: `packages/wwv-plugin-maritime/src/index.ts`
- Modify: `packages/wwv-plugin-military-aviation/src/index.ts`
- [ ] **Step 1: Update plugin classes**
For each file above, modify the imports and the class body:
```typescript
import pkg from "../package.json";
// ...
export class AviationPlugin implements WorldPlugin { // (or extends BasePlugin)
// ...
version = pkg.version;
```
- [ ] **Step 2: Verify compilation**
Run: `pnpm exec tsc --noEmit`
Expected: PASS
- [ ] **Step 3: Commit**
```bash
git commit -am "refactor(plugins): derive version dynamically for core infrastructure plugins [Patch]"
```
## Task 3: Refactor Group B Plugins (Facilities & Infrastructure)
**Files:**
- Modify: `packages/wwv-plugin-airports/src/index.ts`
- Modify: `packages/wwv-plugin-seaports/src/index.ts`
- Modify: `packages/wwv-plugin-spaceports/src/index.ts`
- Modify: `packages/wwv-plugin-embassies/src/index.ts`
- Modify: `packages/wwv-plugin-lighthouses/src/index.ts`
- Modify: `packages/wwv-plugin-nuclear/src/index.ts`
- Modify: `packages/wwv-plugin-undersea-cables/src/index.ts`
- Modify: `packages/wwv-plugin-mineral-mines/src/index.ts`
- [ ] **Step 1: Update plugin classes**
For each file above, replace `version = "..."` with `version = pkg.version` and add `import pkg from "../package.json";`.
- [ ] **Step 2: Verify compilation**
Run: `pnpm exec tsc --noEmit`
Expected: PASS
- [ ] **Step 3: Commit**
```bash
git commit -am "refactor(plugins): derive version dynamically for facility plugins [Patch]"
```
## Task 4: Refactor Group C Plugins (Hazards & Events)
**Files:**
- Modify: `packages/wwv-plugin-earthquakes/src/index.ts`
- Modify: `packages/wwv-plugin-volcanoes/src/index.ts`
- Modify: `packages/wwv-plugin-wildfire/src/index.ts`
- Modify: `packages/wwv-plugin-conflict-events/src/index.tsx`
- Modify: `packages/wwv-plugin-conflict-zones/src/index.tsx`
- Modify: `packages/wwv-plugin-civil-unrest/src/index.tsx`
- Modify: `packages/wwv-plugin-cyber-attacks/src/index.tsx`
- Modify: `packages/wwv-plugin-international-sanctions/src/index.tsx`
- [ ] **Step 1: Update plugin classes**
For each file above, replace `version = "..."` with `version = pkg.version` and add `import pkg from "../package.json";`. Note that some files are `.tsx`.
- [ ] **Step 2: Verify compilation**
Run: `pnpm exec tsc --noEmit`
Expected: PASS
- [ ] **Step 3: Commit**
```bash
git commit -am "refactor(plugins): derive version dynamically for event and hazard plugins [Patch]"
```
## Task 5: Refactor Group D Plugins (Misc & Utilities)
**Files:**
- Modify: `packages/wwv-plugin-satellite/src/index.ts`
- Modify: `packages/wwv-plugin-surveillance-satellites/src/index.tsx`
- Modify: `packages/wwv-plugin-osm-search/src/index.ts`
- Modify: `packages/wwv-plugin-iranwarlive/src/index.ts`
- Modify: `packages/wwv-plugin-daynight/src/index.ts`
- Modify: `packages/wwv-plugin-camera/src/index.ts`
- Modify: `packages/wwv-plugin-borders/src/index.ts`
- Modify: `packages/wwv-plugin-gps-jamming/src/index.tsx`
- Modify: `packages/wwv-plugin-air-defense/src/index.tsx`
- [ ] **Step 1: Update plugin classes**
For each file above, replace `version = "..."` with `version = pkg.version` and add `import pkg from "../package.json";`.
- [ ] **Step 2: Verify compilation and tests**
Run: `pnpm exec tsc --noEmit`
Run: `pnpm test`
Expected: PASS
- [ ] **Step 3: Commit**
```bash
git commit -am "refactor(plugins): derive version dynamically for utility plugins [Patch]"
```
@@ -1,124 +0,0 @@
# Demo Default Plugins Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Enable specific plugins by default on the demo edition via environment variables so the user is immediately impressed.
**Architecture:** Update `layersSlice.ts` to accept an optional `defaultEnabled` parameter in `initLayer`. In `AppShell.tsx`, look up `NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS` when the edition is `demo`, and pass the flag true to `initLayer` for matching plugins during registration. Document the variable in `.env.example`.
**Tech Stack:** Next.js, Zustand, TypeScript.
---
### Task 1: Update layer slice definition
**Files:**
- Modify: `src/core/state/layersSlice.ts`
- [ ] **Step 1: Write the implementation**
Update `initLayer` in `src/core/state/layersSlice.ts` to accept a second parameter:
```typescript
// Add defaultEnabled parameter to the interface
export interface LayersSlice {
// ...
initLayer: (pluginId: string, defaultEnabled?: boolean) => void;
}
// ...
// Use the parameter in the state updater
initLayer: (pluginId, defaultEnabled = false) =>
set((state) => ({
layers: {
...state.layers,
[pluginId]: state.layers[pluginId] || { enabled: defaultEnabled, entityCount: 0, loading: false },
},
})),
```
- [ ] **Step 2: Commit**
```bash
git add src/core/state/layersSlice.ts
npm run commit -- "feat: add defaultEnabled param to initLayer in layers slice"
```
### Task 2: Apply default configuration in AppShell
**Files:**
- Modify: `src/components/layout/AppShell.tsx`
- [ ] **Step 1: Write the implementation**
Add `isDemo` import at the top of `src/components/layout/AppShell.tsx`:
```typescript
import { isDemo } from "@/core/edition";
```
In `AppShell.tsx`, around line 71, inside `startPlatform()`, fetch the value from the environment if the instance is demo:
```typescript
// Fetch disabled built-in plugins before registration
let disabledIds = new Set<string>();
// ... (keep existing try/catch block)
// Setup demo defaults
const demoDefaultPlugins = new Set<string>();
if (isDemo) {
const envVar = process.env.NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS || "";
envVar.split(",").forEach(s => {
const clean = s.trim();
if (clean) demoDefaultPlugins.add(clean);
});
}
```
Then update the `pluginManager` registration loop to inject the boolean for `initLayer`:
```typescript
for (const plugin of pluginRegistry.getAll()) {
await pluginManager.registerPlugin(plugin);
initLayer(plugin.id, demoDefaultPlugins.has(plugin.id));
}
```
- [ ] **Step 2: Run test to verify it passes**
Run type checks to verify no compilation issues:
`npx tsc --noEmit`
- [ ] **Step 3: Commit**
```bash
git add src/components/layout/AppShell.tsx
npm run commit -- "feat: parse and apply default demo plugins via NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS"
```
### Task 3: Document environment definitions
**Files:**
- Modify: `.env.example`
- Modify: `.env`
- [ ] **Step 1: Write the implementation**
Update `.env.example` and `.env` around the `NEXT_PUBLIC_WWV_EDITION=local` definition:
```dotenv
# Default plugins enabled on boot for demo edition
# Comma-separated list of plugin IDs (e.g. aviation,maritime,iranwarlive)
NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS=
# Edition: "local" | "cloud" | "demo"
NEXT_PUBLIC_WWV_EDITION=local
```
- [ ] **Step 2: Commit**
```bash
git add .env.example .env
npm run commit -- "docs: add NEXT_PUBLIC_DEMO_DEFAULT_PLUGINS to env templates"
```
@@ -1,177 +0,0 @@
# Decouple Plugin Proxies Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Strip out hardcoded proxy endpoints from the `worldwideview` core repository to enforce a fully decoupled plugin ecosystem, replacing them with direct browser fetching or a universal CORS proxy.
**Architecture:** Remove preferential API routes (`/api/earthquake`, `/api/undersea-cables`, `/api/camera/*`) from the `worldwideview` core app. Promote the existing camera proxy to a universal `/api/proxy` with strict SSRF defenses. Provide direct browser-fetch code for the `wwv-plugin-earthquakes` where CORS permits, and migrate traffic camera fetchers directly into the `wwv-plugin-camera` package to fetch via the universal proxy.
**Tech Stack:** Next.js 16 (App Router), TypeScript, pnpm workspace
---
### Task 1: Promote Universal Proxy in Core Repository
**Files:**
- Create (Move): `src/app/api/proxy/route.ts`
- Delete: `src/app/api/camera/proxy/route.ts`
- [ ] **Step 1: Relocate the proxy route and update logs**
Move the existing camera proxy to act as a system-wide universal proxy.
Run: `mkdir -p src/app/api/proxy`
Run: `mv src/app/api/camera/proxy/route.ts src/app/api/proxy/route.ts`
- [ ] **Step 2: Update the error logging prefix in the new file**
Modify `src/app/api/proxy/route.ts` near line 97:
```json
{
"instruction": "Update the error logging prefix",
"replace_chunks": [
{
"start_line": 96,
"end_line": 98,
"target_content": " } catch (error: any) {\n console.error(\"[CameraProxy] Error fetching target URL:\", error);\n return NextResponse.json(",
"replacement_content": " } catch (error: any) {\n console.error(\"[UniversalProxy] Error fetching target URL:\", error);\n return NextResponse.json("
}
]
}
```
- [ ] **Step 3: Commit the Universal Proxy**
```bash
git add src/app/api/proxy/route.ts src/app/api/camera/proxy/route.ts
git commit -m "refactor: promote camera proxy to universal proxy"
```
### Task 2: Strip Preferential Proxy Routes From Core Application
**Files:**
- Delete: `src/app/api/earthquake/route.ts`
- Delete: `src/app/api/undersea-cables/route.ts`
- Delete: everything in `src/app/api/camera` codebase (`caltrans`, `extract`, `gdot`, `test`, `tfl`, `traffic`)
- [ ] **Step 1: Delete all plugin-specific Next.js API routes**
Run: `rm -rf src/app/api/earthquake`
Run: `rm -rf src/app/api/undersea-cables`
**WAIT**: For `src/app/api/camera`, we must physically copy the fetchers into `worldwideview-plugins` before we delete them.
Run: `cp -r src/app/api/camera/caltrans ../worldwideview-plugins/packages/wwv-plugin-camera/src/`
Run: `cp -r src/app/api/camera/gdot ../worldwideview-plugins/packages/wwv-plugin-camera/src/`
Run: `cp -r src/app/api/camera/tfl ../worldwideview-plugins/packages/wwv-plugin-camera/src/`
Run: `rm -rf src/app/api/camera`
- [ ] **Step 2: Commit the deleted API routes**
```bash
git add src/app/api/earthquake src/app/api/undersea-cables src/app/api/camera
git commit -m "refactor!: strip preferential plugin APIs from core"
```
### Task 3: Migrate Earthquakes and Undersea Cables Plugins
**Files:**
- Modify: `../worldwideview-plugins/packages/wwv-plugin-earthquakes/src/index.ts`
- Modify: `../worldwideview-plugins/packages/wwv-plugin-undersea-cables/src/index.ts`
- [ ] **Step 1: Update Earthquakes plugin to direct browser fetch (Option A)**
In `../worldwideview-plugins/packages/wwv-plugin-earthquakes/src/index.ts`, replace the `/api/earthquake` fetch with the USGS direct URL.
```json
{
"instruction": "Replace the API fetch with direct USGS fetch and remove apiBasePath",
"replace_chunks": [
{
"start_line": 38,
"end_line": 40,
"target_content": " try {\n const res = await globalThis.fetch(`/api/earthquake`);\n if (!res.ok) {",
"replacement_content": " try {\n const res = await globalThis.fetch(`https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson`);\n if (!res.ok) {"
},
{
"start_line": 94,
"end_line": 96,
"target_content": " getServerConfig(): ServerPluginConfig {\n return { apiBasePath: \"/api/earthquake\", pollingIntervalMs: 120000, historyEnabled: false };\n }",
"replacement_content": " getServerConfig(): ServerPluginConfig {\n return { pollingIntervalMs: 120000, historyEnabled: false };\n }"
}
]
}
```
- [ ] **Step 2: Update Undersea Cables plugin to use Universal Proxy (Option B)**
In `../worldwideview-plugins/packages/wwv-plugin-undersea-cables/src/index.ts`:
```json
{
"instruction": "Proxy route to universal proxy",
"replace_chunks": [
{
"start_line": 35,
"end_line": 37,
"target_content": " // Proxy route to bypass CORS for Telegeography submarine cable map API\n const url = \"/api/undersea-cables\";\n ",
"replacement_content": " // Proxy route to bypass CORS for Telegeography submarine cable map API\n const targetUrl = encodeURIComponent(\"https://www.submarinecablemap.com/api/v3/cable/cable-geo.json\");\n const url = `/api/proxy?url=${targetUrl}`;\n "
}
]
}
```
- [ ] **Step 3: Commit the plugin migrations**
```bash
cd ../worldwideview-plugins
git add packages/wwv-plugin-earthquakes/src/index.ts packages/wwv-plugin-undersea-cables/src/index.ts
git commit -m "refactor: transition earthquake and undersea cables to decoupled fetching"
cd ../worldwideview
```
### Task 4: Refactor Camera Plugin to Fetch Natively
**Files:**
- Modify: `../worldwideview-plugins/packages/wwv-plugin-camera/src/index.ts`
- Delete: `caltrans`, `gdot`, `tfl` previously copied components (combine into `trafficFetchers.ts`)
- [ ] **Step 1: Consolidate the camera fetchers**
Create `../worldwideview-plugins/packages/wwv-plugin-camera/src/trafficFetchers.ts`.
Migrate the code from the `caltransFetcher.ts`, `gdotFetcher.ts`, and `tflFetcher.ts` files that we copied in Task 2.
Crucially, when doing `fetch(...)` in these fetchers, if the endpoint doesn't support CORS, wrap it in `/api/proxy?url=${encodeURIComponent(...) }` so the browser can fetch it. Ensure the data models align.
- [ ] **Step 2: Update `wwv-plugin-camera/src/index.ts` to call the fetchers natively**
In `../worldwideview-plugins/packages/wwv-plugin-camera/src/index.ts` function `loadTrafficCameras()`:
```json
{
"instruction": "Replace API fetch with native client-side parallel fetching",
"replace_chunks": [
{
"start_line": 106,
"end_line": 118,
"target_content": " private async loadTrafficCameras(): Promise<void> {\n try {\n const res = await fetch(\"/api/camera/traffic\");\n if (!res.ok) throw new Error(`API returned ${res.status}`);\n const data = await res.json();\n if (data.cameras && Array.isArray(data.cameras)) {\n this.sourceBuckets[\"default\"] = data.cameras.map(\n (f: unknown, i: number) => mapGeoJsonFeature(f, i, \"traffic\"),\n );\n }\n } catch (err) {\n console.warn(\"[CameraPlugin] Traffic cameras API failed:\", err);\n }",
"replacement_content": " private async loadTrafficCameras(): Promise<void> {\n try {\n const { fetchCaltrans, fetchGdot, fetchTfl } = await import(\"./trafficFetchers\");\n const [caltrans, gdot, tfl] = await Promise.allSettled([\n fetchCaltrans(), fetchGdot(), fetchTfl()\n ]);\n \n const cameras = [];\n if (caltrans.status === \"fulfilled\") cameras.push(...caltrans.value);\n if (gdot.status === \"fulfilled\") cameras.push(...gdot.value);\n if (tfl.status === \"fulfilled\") cameras.push(...tfl.value);\n\n if (cameras.length > 0) {\n this.sourceBuckets[\"default\"] = cameras.map(\n (f: unknown, i: number) => mapGeoJsonFeature(f, i, \"traffic\"),\n );\n }\n } catch (err) {\n console.warn(\"[CameraPlugin] Traffic cameras API failed:\", err);\n }"
}
]
}
```
- [ ] **Step 3: Remove the extra node API files from the plugin source tree**
Run: `rm -rf ../worldwideview-plugins/packages/wwv-plugin-camera/src/caltrans`
Run: `rm -rf ../worldwideview-plugins/packages/wwv-plugin-camera/src/gdot`
Run: `rm -rf ../worldwideview-plugins/packages/wwv-plugin-camera/src/tfl`
- [ ] **Step 4: Commit Camera plugin refactoring**
```bash
cd ../worldwideview-plugins
git add packages/wwv-plugin-camera/src
git commit -m "feat: migrate traffic camera fetchers to client-side plugin bundle"
cd ../worldwideview
```
-42
View File
@@ -1,42 +0,0 @@
<!-- Generated: 2026-04-23 06:11:00 UTC -->
# Testing
## Overview
WorldWideView utilizes Vitest alongside a `jsdom` environment and the React Testing Library to ensure high reliability across core application logic, server APIs, and plugin loaders. Test coverage is strategically focused on shared libraries, core state logic, and the plugin ecosystem mechanisms.
## Test Types
### Unit Tests
Focused on validating standalone functions and state slice reducers without mounting React components.
- **Example:** Validating the runtime edition feature flags.
- *File:* `src/core/edition.test.ts`
- **Example:** Validating marketplace token exchanges and rate limiting logic.
- *Files:* `src/lib/marketplaceToken.test.ts`, `src/lib/rateLimit.test.ts`
### Integration Tests
Focused on ensuring module interaction, such as the event bus properly interacting with state, or plugin loaders successfully resolving manifests.
- **Example:** Testing local database repositories.
- *File:* `src/lib/repository.test.ts`
- **Example:** Validating cross-origin resource sharing (CORS) handlers for data engine streaming.
- *File:* `src/lib/cors.test.ts`
- **Example:** Verifying demo-admin bypass secrets.
- *File:* `src/lib/demoAdmin.test.ts`
## Running Tests
Execute the following commands from the root `worldwideview` directory:
- **Run all tests once:**
```bash
pnpm test
```
*(Alias for `vitest run`)*
- **Run tests in watch mode (for active development):**
```bash
npx vitest
```
## Reference
- **Coverage Scope:** The Vitest configuration primarily targets tests located inside `src/lib/**`, `src/core/**`, and `src/plugins/**`.
- **Environment:** The test environment is configured as `jsdom` via `vite.config.ts` or `vitest.config.ts`, ensuring that DOM-specific API calls function outside of a real browser.
-6
View File
@@ -1,6 +0,0 @@
const { PrismaClient } = require('./src/generated/prisma');
const prisma = new PrismaClient();
prisma.installedPlugin.findMany().then(r => console.log(JSON.stringify(r.map(record => {
const manifest = JSON.parse(record.config);
return { id: manifest.id, entry: manifest.entry, format: manifest.format };
}), null, 2))).catch(console.error).finally(() => prisma.$disconnect());
-9
View File
@@ -1,9 +0,0 @@
import sqlite3
import json
conn = sqlite3.connect('data/wwv.db')
cursor = conn.cursor()
cursor.execute('SELECT id, dataSource FROM installed_plugins')
rows = cursor.fetchall()
for r in rows:
if r[1]:
print(f"plugin={r[0]}, dataSource={r[1]}")
-37
View File
@@ -1,37 +0,0 @@
Write-Host "[*] Setting up WorldWideView for Local Development..."
# Check for pnpm
try {
$null = Get-Command pnpm -ErrorAction Stop
} catch {
Write-Host "[Error] pnpm is not installed or not in PATH."
Write-Host "Please install it first: https://pnpm.io/installation"
exit 1
}
Write-Host "[*] Installing dependencies..."
pnpm install
Write-Host "[*] Running initial setup (generating secrets)..."
pnpm run setup
# Check for the sibling Data Engine repository
if (-not (Test-Path "../wwv-data-engine")) {
Write-Host ""
Write-Host "=====================================================================" -ForegroundColor Yellow
Write-Host "[!] NOTICE: Local Data Engine not found at ../wwv-data-engine" -ForegroundColor Yellow
Write-Host ""
Write-Host "Frontend-Only Mode: You are developing the frontend UI." -ForegroundColor Green
Write-Host "WorldWideView will automatically stream data from the Cloud Engine." -ForegroundColor Green
Write-Host ""
Write-Host "Full-Stack Mode: If you want to develop backend data seeders, you" -ForegroundColor Cyan
Write-Host "must clone the open-source data engine as a sibling directory:" -ForegroundColor Cyan
Write-Host " cd ..; git clone https://github.com/silvertakana/wwv-data-engine"
Write-Host " cd wwv-data-engine; pnpm install"
Write-Host "=====================================================================" -ForegroundColor Yellow
Write-Host ""
}
Write-Host "[*] Starting local Next.js frontend server..."
Write-Host " (To run the data engine backends concurrently, run: pnpm dev:all)"
pnpm run dev
-38
View File
@@ -1,38 +0,0 @@
#!/bin/bash
set -e
echo "🌍 Setting up WorldWideView for Local Development..."
# Check for pnpm
if ! command -v pnpm &> /dev/null; then
echo "❌ Error: pnpm is required but not installed."
echo "Please install it first: https://pnpm.io/installation"
exit 1
fi
echo "📦 Installing dependencies..."
pnpm install
echo "🔐 Running initial setup (generating secrets)..."
pnpm run setup
# Check for the sibling Data Engine repository
if [ ! -d "../wwv-data-engine" ]; then
echo ""
echo "====================================================================="
echo "⚠️ NOTICE: Local Data Engine not found at ../wwv-data-engine"
echo ""
echo "Frontend-Only Mode: You are developing the frontend UI."
echo "WorldWideView will automatically stream data from the Cloud Engine."
echo ""
echo "Full-Stack Mode: If you want to develop backend data seeders, you"
echo "must clone the open-source data engine as a sibling directory:"
echo " cd .. && git clone https://github.com/silvertakana/wwv-data-engine"
echo " cd wwv-data-engine && pnpm install"
echo "====================================================================="
echo ""
fi
echo "🚀 Starting local Next.js frontend server..."
echo " (To run the data engine backends concurrently, run: pnpm dev:all)"
pnpm run dev
View File
Whitespace-only changes.
+36 -25
View File
@@ -3,8 +3,30 @@ import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
serverExternalPackages: ["better-sqlite3", "@prisma/adapter-better-sqlite3", "@prisma/client", "prisma"],
transpilePackages: ["@worldwideview/wwv-plugin-sdk", "resium", "react-player", "satellite.js"],
allowedDevOrigins: process.env.ALLOWED_DEV_ORIGIN ? [process.env.ALLOWED_DEV_ORIGIN] : undefined,
transpilePackages: [
"@worldwideview/wwv-plugin-aviation",
"@worldwideview/wwv-plugin-borders",
"@worldwideview/wwv-plugin-camera",
"@worldwideview/wwv-plugin-conflict-events",
"@worldwideview/wwv-plugin-civil-unrest",
"@worldwideview/wwv-plugin-daynight",
"@worldwideview/wwv-plugin-undersea-cables",
"@worldwideview/wwv-plugin-earthquakes",
"@worldwideview/wwv-plugin-iranwarlive",
"@worldwideview/wwv-plugin-maritime",
"@worldwideview/wwv-plugin-military-aviation",
"@worldwideview/wwv-plugin-satellite",
"@worldwideview/wwv-plugin-gps-jamming",
"@worldwideview/wwv-plugin-surveillance-satellites",
"@worldwideview/wwv-plugin-cyber-attacks",
"@worldwideview/wwv-plugin-international-sanctions",
"@worldwideview/wwv-plugin-sdk",
"@worldwideview/wwv-plugin-wildfire",
"@worldwideview/wwv-plugin-osm-search",
"resium",
"react-player",
"satellite.js"
],
experimental: {
memoryBasedWorkersCount: true,
cpus: 2,
@@ -23,7 +45,7 @@ const nextConfig: NextConfig = {
value: [
"default-src 'self'",
// CesiumJS requires unsafe-eval (worker compilation) and unsafe-inline (styles)
"script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: https://unpkg.com https://cdn.jsdelivr.net https://analytics.worldwideview.dev https://va.vercel-scripts.com https://pagead2.googlesyndication.com https://adservice.google.com https://www.googletagservices.com https://ep2.adtrafficquality.google https://static.cloudflareinsights.com",
"script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: https://cdn.jsdelivr.net https://analytics.worldwideview.dev https://va.vercel-scripts.com https://pagead2.googlesyndication.com https://adservice.google.com https://www.googletagservices.com https://ep2.adtrafficquality.google https://static.cloudflareinsights.com",
"style-src 'self' 'unsafe-inline' fonts.googleapis.com",
"font-src 'self' fonts.gstatic.com",
// Camera streams load images/MJPEG from arbitrary IPs worldwide — http: https: required
@@ -50,7 +72,16 @@ const nextConfig: NextConfig = {
},
];
},
async rewrites() {
return [
{
source: "/api/external/:source*",
// Proxy to the shared data engine locally or over docker network
// We use process.env to override the url if running Next.js outside docker
destination: `${process.env.WWV_DATA_ENGINE_URL || "http://wwv-data-engine:5001"}/data/:source*`,
},
];
},
outputFileTracingExcludes: {
"*": ["./public/cesium/**"],
},
@@ -82,24 +113,4 @@ const nextConfig: NextConfig = {
},
};
import { withSentryConfig } from "@sentry/nextjs";
export default withSentryConfig(nextConfig, {
// For all available options, see:
// https://github.com/getsentry/sentry-webpack-plugin#options
org: process.env.SENTRY_ORG,
project: process.env.SENTRY_PROJECT,
sentryUrl: process.env.GLITCHTIP_SERVER_URL,
authToken: process.env.SENTRY_AUTH_TOKEN,
// Automatically tree-shake Sentry logger statements to reduce bundle size
disableLogger: true,
// Hides source maps from generated client bundles
sourcemaps: {
disable: true,
},
// Upload a larger set of source maps for prettier stack traces (increases build time)
widenClientFileUpload: true,
});
export default nextConfig;
+23 -8
View File
@@ -1,29 +1,47 @@
{
"name": "worldwideview",
"version": "1.20.0",
"version": "1.8.3",
"private": true,
"scripts": {
"setup": "node scripts/setup.mjs",
"test-worktree": "node scripts/test-worktree.mjs",
"clean": "node -e \"const fs=require('fs');fs.rmSync('.next',{recursive:true,force:true})\"",
"dev": "next dev --webpack",
"dev:all": "concurrently -n \"next,backends\" -c \"magenta,blue\" \"pnpm dev\" \"pnpm dev:backends\"",
"dev:backends": "cd ../wwv-data-engine && pnpm dev",
"dev:all": "npx concurrently \"pnpm dev\" \"pnpm --filter wwv-data-engine dev\"",
"predev": "npx prisma migrate deploy && node scripts/copy-cesium.mjs",
"copy-cesium": "node scripts/copy-cesium.mjs",
"build": "next build --webpack",
"start": "next start",
"test": "vitest run",
"start:backends": "pnpm --filter wwv-data-engine start",
"dev:backends": "pnpm --filter wwv-data-engine dev",
"clean:backends": "pnpm --filter wwv-data-engine clean:db",
"db:reset": "npx prisma migrate reset --force"
},
"dependencies": {
"@auth/prisma-adapter": "^2.11.1",
"@prisma/adapter-better-sqlite3": "^7.5.0",
"@prisma/client": "^7.5.0",
"@sentry/nextjs": "^10.48.0",
"@supabase/supabase-js": "^2.98.0",
"@vercel/analytics": "^1.6.1",
"@worldwideview/wwv-plugin-aviation": "workspace:*",
"@worldwideview/wwv-plugin-borders": "workspace:*",
"@worldwideview/wwv-plugin-camera": "workspace:*",
"@worldwideview/wwv-plugin-civil-unrest": "workspace:*",
"@worldwideview/wwv-plugin-conflict-events": "workspace:*",
"@worldwideview/wwv-plugin-cyber-attacks": "workspace:*",
"@worldwideview/wwv-plugin-daynight": "workspace:*",
"@worldwideview/wwv-plugin-earthquakes": "workspace:*",
"@worldwideview/wwv-plugin-gps-jamming": "workspace:*",
"@worldwideview/wwv-plugin-international-sanctions": "workspace:*",
"@worldwideview/wwv-plugin-iranwarlive": "workspace:*",
"@worldwideview/wwv-plugin-maritime": "workspace:*",
"@worldwideview/wwv-plugin-military-aviation": "workspace:*",
"@worldwideview/wwv-plugin-satellite": "workspace:*",
"@worldwideview/wwv-plugin-sdk": "workspace:*",
"@worldwideview/wwv-plugin-surveillance-satellites": "workspace:*",
"@worldwideview/wwv-plugin-undersea-cables": "workspace:*",
"@worldwideview/wwv-plugin-wildfire": "workspace:*",
"bcryptjs": "^3.0.3",
"cesium": "^1.139.0",
"cheerio": "^1.2.0",
@@ -31,7 +49,7 @@
"insecam-api": "^0.0.3",
"jose": "^6.2.2",
"lucide-react": "^0.576.0",
"next": "16.2.3",
"next": "16.2.1",
"next-auth": "^5.0.0-beta.30",
"prisma": "^7.5.0",
"react": "19.2.3",
@@ -53,12 +71,9 @@
"@types/react-dom": "^19",
"@types/ws": "^8.18.1",
"@vitejs/plugin-react": "^5.1.4",
"concurrently": "^9.2.1",
"copy-webpack-plugin": "^14.0.0",
"jsdom": "^28.1.0",
"rollup-plugin-external-globals": "^0.13.0",
"typescript": "^5",
"vite": "^8.0.8",
"vitest": "^4.0.18"
},
"pnpm": {
+16
View File
@@ -0,0 +1,16 @@
{
"name": "@worldwideview/create-plugin",
"version": "0.1.0",
"description": "Scaffold a new WorldWideView plugin",
"type": "module",
"bin": {
"create-wwv-plugin": "./dist/index.mjs"
},
"files": ["dist", "templates"],
"scripts": {
"build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.mjs"
},
"devDependencies": {
"esbuild": "^0.25.0"
}
}
+10
View File
@@ -0,0 +1,10 @@
#!/usr/bin/env node
import { scaffold } from "./scaffold.js";
const name = process.argv[2];
if (!name) {
console.error("Usage: npx @worldwideview/create-plugin <plugin-name>");
process.exit(1);
}
scaffold(name);
@@ -0,0 +1,45 @@
import { mkdirSync, writeFileSync, readFileSync, readdirSync } from "fs";
import { join, resolve, dirname } from "path";
import { fileURLToPath } from "url";
const __dirname = dirname(fileURLToPath(import.meta.url));
export function scaffold(name: string): void {
const slug = name.toLowerCase().replace(/[^a-z0-9-]/g, "-");
const dir = resolve(process.cwd(), slug);
console.log(`\n🌍 Creating WorldWideView plugin: ${slug}\n`);
mkdirSync(join(dir, "src"), { recursive: true });
const templateDir = join(__dirname, "..", "templates");
const files = readdirSync(templateDir);
for (const file of files) {
let content = readFileSync(join(templateDir, file), "utf8");
content = content.replace(/\{\{SLUG\}\}/g, slug);
content = content.replace(
/\{\{NAME\}\}/g,
slug
.split("-")
.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
.join(""),
);
// Strip .tpl extension and route index.ts into src/
const outName = file.replace(/\.tpl$/, "");
const dest =
outName === "index.ts"
? join(dir, "src", outName)
: join(dir, outName);
writeFileSync(dest, content);
console.log(` ✓ ${outName === "index.ts" ? "src/" + outName : outName}`);
}
console.log(`\n✅ Done! Next steps:`);
console.log(` cd ${slug}`);
console.log(` npm install`);
console.log(` npm run dev # Watch mode`);
console.log(` npm run build # Production bundle`);
console.log(` npm publish # Publish to npm\n`);
}
@@ -0,0 +1,48 @@
/**
* {{NAME}} — WorldWideView Plugin
*
* Build with: npm run build
* Publish with: npm publish
*/
import type {
WorldPlugin,
GeoEntity,
TimeRange,
PluginContext,
LayerConfig,
CesiumEntityOptions,
PluginCategory,
} from "@worldwideview/wwv-plugin-sdk";
export default class {{NAME}}Plugin implements WorldPlugin {
readonly id = "{{SLUG}}";
readonly name = "{{NAME}}";
readonly description = "A custom WorldWideView plugin";
readonly icon = "📍";
readonly category: PluginCategory = "custom";
readonly version = "1.0.0";
async initialize(_ctx: PluginContext): Promise<void> {
console.log(`[{{NAME}}] Initialized`);
}
destroy(): void {}
async fetch(_timeRange: TimeRange): Promise<GeoEntity[]> {
// Replace with your data source
return [];
}
getPollingInterval(): number {
return 60_000;
}
getLayerConfig(): LayerConfig {
return { color: "#3b82f6", clusterEnabled: true, clusterDistance: 40 };
}
renderEntity(_entity: GeoEntity): CesiumEntityOptions {
return { type: "point", color: "#3b82f6", size: 6 };
}
}
@@ -0,0 +1,21 @@
{
"name": "wwv-plugin-{{SLUG}}",
"version": "1.0.0",
"description": "WorldWideView plugin: {{NAME}}",
"type": "module",
"module": "dist/index.mjs",
"files": ["dist"],
"scripts": {
"build": "vite build",
"dev": "vite build --watch"
},
"devDependencies": {
"@worldwideview/wwv-plugin-sdk": "*",
"vite": "^6.0.0",
"rollup-plugin-external-globals": "^0.12.0",
"typescript": "^5.0.0"
},
"peerDependencies": {
"react": "^19.0.0"
}
}
@@ -0,0 +1,13 @@
{
"id": "{{SLUG}}",
"name": "{{NAME}}",
"version": "1.0.0",
"description": "A custom WorldWideView plugin",
"type": "data-layer",
"format": "bundle",
"trust": "unverified",
"capabilities": ["data:own"],
"category": "custom",
"icon": "📍",
"entry": "dist/index.mjs"
}
@@ -0,0 +1,12 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"jsx": "react-jsx",
"declaration": false,
"outDir": "dist"
},
"include": ["src"]
}
@@ -0,0 +1,24 @@
import { defineConfig } from "vite";
import externalGlobals from "rollup-plugin-external-globals";
export default defineConfig({
build: {
lib: {
entry: "src/index.ts",
formats: ["es"],
fileName: "index",
},
rollupOptions: {
external: ["react", "react-dom", "react/jsx-runtime"],
plugins: [
externalGlobals({
"react": "globalThis.__WWV_HOST__.React",
"react-dom": "globalThis.__WWV_HOST__.ReactDOM",
"react/jsx-runtime": "globalThis.__WWV_HOST__.jsxRuntime",
}),
],
},
minify: true,
sourcemap: false,
},
});
-2
View File
@@ -1,2 +0,0 @@
#!/usr/bin/env node
require('../dist/index.js');
-24
View File
@@ -1,24 +0,0 @@
{
"name": "@worldwideview/cli",
"version": "1.0.0",
"bin": {
"wwv": "./bin/wwv.js"
},
"scripts": {
"build": "tsc",
"test": "vitest run"
},
"dependencies": {
"archiver": "^7.0.1",
"commander": "^11.1.0",
"vite": "^8.0.8",
"ws": "^8.20.0"
},
"devDependencies": {
"@types/archiver": "^7.0.0",
"@types/node": "^20.0.0",
"@types/ws": "^8.18.1",
"typescript": "^5.0.0",
"vitest": "^1.0.0"
}
}
-64
View File
@@ -1,64 +0,0 @@
import fs from "fs";
import path from "path";
export async function createPlugin(name: string, basePath: string = process.cwd()) {
const targetDir = path.join(basePath, name);
if (fs.existsSync(targetDir)) {
throw new Error(`Directory ${name} already exists`);
}
fs.mkdirSync(targetDir, { recursive: true });
fs.mkdirSync(path.join(targetDir, "src"), { recursive: true });
const manifest = {
manifest_version: 1,
id: name,
name: name,
version: "1.0.0",
description: "A WorldWideView plugin",
type: "data-layer",
category: "custom",
icon: "Box",
capabilities: ["data:own"],
entry: "dist/frontend.mjs",
dev_entry: "src/index.ts"
};
fs.writeFileSync(
path.join(targetDir, "wwv-manifest.json"),
JSON.stringify(manifest, null, 2)
);
const indexContent = `export default class MyPlugin {
id = "${name}";
name = "${name}";
version = "1.0.0";
category = "custom";
icon = "Box";
async initialize(ctx) {
console.log("Initialized", this.id);
}
destroy() {}
async fetch(timeRange) {
return [];
}
getPollingInterval() {
return 5000;
}
getLayerConfig() {
return { color: "#3b82f6", clusterEnabled: true, clusterDistance: 50 };
}
renderEntity(entity) {
return { type: "point", color: "#3b82f6", size: 6 };
}
}
`;
fs.writeFileSync(path.join(targetDir, "src", "index.ts"), indexContent);
console.log(`Plugin ${name} scaffolded successfully in ./${name}`);
}
-61
View File
@@ -1,61 +0,0 @@
import fs from "fs";
import path from "path";
import { createServer } from "vite";
import { WebSocketServer } from "ws";
export async function startDevServer(targetUrl: string = "http://localhost:3000") {
const cwd = process.cwd();
const manifestPath = path.join(cwd, "wwv-manifest.json");
if (!fs.existsSync(manifestPath)) {
throw new Error("No wwv-manifest.json found in current directory");
}
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
const port = 24601;
// Start Vite Dev Server
const vite = await createServer({
root: cwd,
server: { port, cors: true, hmr: false }, // We handle HMR via custom WS
plugins: [{
name: 'wwv-hmr',
handleHotUpdate({ server }: any) {
// When Vite detects file changes, broadcast to our custom WS
wss.clients.forEach(client => {
client.send(JSON.stringify({ type: "plugin:updated", pluginId: manifest.id }));
});
return []; // Prevent default Vite HMR
}
}]
});
await vite.listen();
// Attach custom WebSocket server for WWV DevModeSubscriber
const wss = new WebSocketServer({ server: vite.httpServer as any, path: "/__wwv_dev__" });
wss.on("connection", (ws) => {
console.log(`[WWV CLI] Connected to WorldWideView instance`);
ws.send(JSON.stringify({ type: "plugin:added", manifest }));
});
// Notify WorldWideView via API
try {
await fetch(`${targetUrl}/api/dev/load-unpacked`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
...manifest,
entry: `http://localhost:${port}/${manifest.dev_entry || "src/index.ts"}`
})
});
console.log(`[WWV CLI] Registered with WorldWideView at ${targetUrl}`);
} catch (err: any) {
console.error(`[WWV CLI] Failed to connect to ${targetUrl}: ${err.message}`);
console.log(`Waiting for WorldWideView to connect via WebSocket...`);
}
console.log(`\n🚀 Dev server running on http://localhost:${port}`);
console.log(`Watching for file changes in ${cwd}...\n`);
}
-57
View File
@@ -1,57 +0,0 @@
import fs from "fs";
import path from "path";
import { build } from "vite";
import archiver from "archiver";
export async function packagePlugin() {
const cwd = process.cwd();
const manifestPath = path.join(cwd, "wwv-manifest.json");
if (!fs.existsSync(manifestPath)) {
throw new Error("No wwv-manifest.json found in current directory");
}
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
console.log(`[WWV CLI] Building production bundle...`);
await build({
root: cwd,
build: {
lib: {
entry: path.resolve(cwd, manifest.dev_entry || "src/index.ts"),
name: 'WWVPlugin',
formats: ['es'],
fileName: () => 'frontend.mjs'
},
outDir: 'dist',
emptyOutDir: true
}
});
const pkgName = `${manifest.id}-${manifest.version}.wwvpkg`;
const outputPath = path.join(cwd, pkgName);
console.log(`[WWV CLI] Creating archive ${pkgName}...`);
await new Promise<void>((resolve, reject) => {
const output = fs.createWriteStream(outputPath);
const archive = archiver("zip", { zlib: { level: 9 } });
output.on("close", () => resolve());
archive.on("error", (err) => reject(err));
archive.pipe(output);
archive.file(manifestPath, { name: "wwv-manifest.json" });
archive.directory(path.join(cwd, "dist"), "dist");
if (fs.existsSync(path.join(cwd, "data"))) {
archive.directory(path.join(cwd, "data"), "data");
}
archive.finalize();
});
console.log(`\n🎉 Success! Package created at ${outputPath}`);
console.log(`You can use this file to sideload the plugin into your WWV instance.`);
}
-72
View File
@@ -1,72 +0,0 @@
import fs from "fs";
import path from "path";
import { build } from "vite";
import { execSync } from "child_process";
export async function publishToNpm() {
const cwd = process.cwd();
const manifestPath = path.join(cwd, "wwv-manifest.json");
if (!fs.existsSync(manifestPath)) {
throw new Error("No wwv-manifest.json found in current directory");
}
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
console.log(`[WWV CLI] Compiling bundle for NPM...`);
await build({
root: cwd,
build: {
lib: {
entry: path.resolve(cwd, manifest.dev_entry || "src/index.ts"),
name: 'WWVPlugin',
formats: ['es'],
fileName: () => 'frontend.mjs'
},
outDir: 'dist',
emptyOutDir: true
}
});
console.log(`[WWV CLI] Generating package.json...`);
// Create a temporary package.json required for NPM publish
const packageJsonPath = path.join(cwd, "package.json");
const packageJson = {
name: manifest.id, // e.g. @username/my-plugin
version: manifest.version,
description: manifest.description,
main: "dist/frontend.mjs",
type: "module",
files: ["dist", "wwv-manifest.json", "data"],
keywords: ["worldwideview", "plugin", manifest.category],
author: manifest.author || ""
};
fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
console.log(`[WWV CLI] Publishing to NPM...`);
try {
execSync(`npm publish --access public`, { stdio: "inherit", cwd });
} catch (err) {
console.error(`[WWV CLI] NPM publish failed. Please ensure you are logged in via 'npm login'.`);
throw err;
} finally {
// Clean up the generated package.json so it doesn't clutter the dev's repo
fs.unlinkSync(packageJsonPath);
}
console.log(`[WWV CLI] Notifying WorldWideView Marketplace...`);
try {
const targetUrl = process.env.WWV_MARKETPLACE_URL || "https://marketplace.worldwideview.dev";
await fetch(`${targetUrl}/api/webhooks/npm-publish`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ pluginId: manifest.id, version: manifest.version })
});
console.log(`[WWV CLI] Marketplace notified.`);
} catch (err: any) {
console.warn(`[WWV CLI] Could not notify marketplace: ${err.message}. It will be indexed on the next sweep.`);
}
console.log(`\n🚀 Success! Version ${manifest.version} published globally to NPM.`);
}
-66
View File
@@ -1,66 +0,0 @@
import { Command } from "commander";
import { createPlugin } from "./commands/create";
const program = new Command();
program
.name("wwv")
.description("WorldWideView Plugin CLI")
.version("1.0.0");
program
.command("create <name>")
.description("Scaffold a new WorldWideView plugin")
.action(async (name) => {
try {
await createPlugin(name);
} catch (err: any) {
console.error("Error:", err.message);
process.exit(1);
}
});
import { startDevServer } from "./commands/dev";
program
.command("dev")
.description("Start the plugin development server with hot-reload")
.option("-t, --target <url>", "Target WorldWideView URL", "http://localhost:3000")
.action(async (options) => {
try {
await startDevServer(options.target);
} catch (err: any) {
console.error("Error:", err.message);
process.exit(1);
}
});
import { packagePlugin } from "./commands/package";
import { publishToNpm } from "./commands/publish";
program
.command("package")
.description("Build and package the plugin into a .wwvpkg file for sideloading")
.action(async () => {
try {
await packagePlugin();
} catch (err: any) {
console.error("Error:", err.message);
process.exit(1);
}
});
program
.command("publish")
.description("Publish the plugin to NPM and notify the WWV Marketplace")
.action(async () => {
try {
await publishToNpm();
} catch (err: any) {
console.error("Error:", err.message);
process.exit(1);
}
});
program.parse();
-21
View File
@@ -1,21 +0,0 @@
import { describe, it, expect, afterEach } from "vitest";
import { createPlugin } from "../src/commands/create";
import fs from "fs";
import path from "path";
describe("create command", () => {
const testDir = path.join(__dirname, "test-plugin");
afterEach(() => {
if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
});
it("should scaffold a new plugin folder with manifest and index.ts", async () => {
await createPlugin("test-plugin", __dirname);
expect(fs.existsSync(path.join(testDir, "wwv-manifest.json"))).toBe(true);
expect(fs.existsSync(path.join(testDir, "src", "index.ts"))).toBe(true);
const manifest = JSON.parse(fs.readFileSync(path.join(testDir, "wwv-manifest.json"), "utf-8"));
expect(manifest.id).toBe("test-plugin");
});
});
-17
View File
@@ -1,17 +0,0 @@
import { describe, it, expect, vi } from "vitest";
import { startDevServer } from "../src/commands/dev";
// Mock vite and ws
vi.mock("vite", () => ({
createServer: vi.fn().mockResolvedValue({
listen: vi.fn(),
httpServer: { on: vi.fn() },
ws: { on: vi.fn() }
})
}));
describe("dev command", () => {
it("should export startDevServer function", () => {
expect(typeof startDevServer).toBe("function");
});
});
-11
View File
@@ -1,11 +0,0 @@
import { describe, it, expect } from "vitest";
import { execSync } from "child_process";
import path from "path";
describe("wwv cli", () => {
it("should print help information", () => {
const binPath = path.resolve(__dirname, "../bin/wwv.js");
const output = execSync(`node ${binPath} --help`).toString();
expect(output).toContain("Usage: wwv [options]");
});
});
-8
View File
@@ -1,8 +0,0 @@
import { describe, it, expect } from "vitest";
import { packagePlugin } from "../src/commands/package";
describe("package command", () => {
it("should export packagePlugin function", () => {
expect(typeof packagePlugin).toBe("function");
});
});
-15
View File
@@ -1,15 +0,0 @@
import { describe, it, expect, vi } from "vitest";
import { publishToNpm } from "../src/commands/publish";
vi.mock("child_process", () => ({
execSync: vi.fn()
}));
vi.mock("vite", () => ({
build: vi.fn().mockResolvedValue({})
}));
describe("publish command", () => {
it("should export publishToNpm function", () => {
expect(typeof publishToNpm).toBe("function");
});
});
-8
View File
@@ -1,8 +0,0 @@
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
environment: "node",
globals: true
}
});
+65
View File
@@ -0,0 +1,65 @@
# Stage 0: Extract package.json files for layer caching
FROM alpine AS extractor
WORKDIR /app
COPY . .
RUN find . -type f \! -name 'package.json' \! -name 'pnpm-workspace.yaml' \! -name 'pnpm-lock.yaml' -delete && \
find . -type d -empty -delete
# Build Stage
FROM node:22-alpine AS builder
# better-sqlite3 requires python3 and build tools for native compilation
RUN apk add --no-cache python3 make g++
WORKDIR /app
# Enable corepack for pnpm
RUN corepack enable
# Copy only the extracted package.jsons
COPY --from=extractor /app ./
# Install dependencies with cache mount for pnpm store
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store pnpm install --filter @worldwideview/wwv-data-engine...
# Copy source and build
COPY packages/wwv-data-engine ./packages/wwv-data-engine
RUN pnpm --filter @worldwideview/wwv-data-engine build
# Production Stage
FROM node:22-alpine
WORKDIR /app
# Enable corepack for pnpm
RUN corepack enable
# Copy only the extracted package.jsons
COPY --from=extractor /app ./
# Install ONLY production dependencies
# Need python/make for building native modules during install
RUN --mount=type=cache,id=pnpm,target=/root/.local/share/pnpm/store \
apk add --no-cache python3 make g++ && \
pnpm install --prod --filter @worldwideview/wwv-data-engine... && \
apk del python3 make g++
# Copy built artifacts from builder
COPY --from=builder /app/packages/wwv-data-engine/dist ./packages/wwv-data-engine/dist
COPY --from=builder /app/packages/wwv-data-engine/seedData ./packages/wwv-data-engine/seedData
# Copy prisma schema and generate client for production
COPY --from=builder /app/packages/wwv-data-engine/prisma ./packages/wwv-data-engine/prisma
RUN cd packages/wwv-data-engine && npx prisma generate
WORKDIR /app/packages/wwv-data-engine
# Create directory for SQLite DB
RUN mkdir -p /app/packages/wwv-data-engine/data
ENV NODE_ENV=production
ENV PORT=5001
EXPOSE 5001
CMD ["node", "dist/server.js"]
@@ -0,0 +1,173 @@
import Database from 'better-sqlite3';
import { PrismaClient } from '@prisma/client';
import path from 'path';
import dotenv from 'dotenv';
dotenv.config({ path: path.join(__dirname, '../../.env.local') });
const prisma = new PrismaClient();
async function main() {
console.log('[Migration] Starting migration from local engine.db to Supabase');
const dbPath = process.argv[2] || path.join(process.cwd(), 'data', 'engine.db');
console.log(`[Migration] Reading from SQLite database at: ${dbPath}`);
const db = new Database(dbPath, { readonly: true });
// 1. Migrate IranwarEvent
try {
console.log('[Migration] Migrating iranwar_events...');
const events = db.prepare('SELECT event_id, payload, timestamp, fetched_at FROM iranwar_events').all();
console.log(`[Migration] Found ${events.length} iranwar_events. Iterating...`);
let count = 0;
for (const evt of events as any[]) {
const parsedTs = typeof evt.timestamp === 'string' ? new Date(evt.timestamp).getTime() : (evt.timestamp || Date.now());
await prisma.iranwarEvent.upsert({
where: { eventId: evt.event_id },
create: {
eventId: evt.event_id,
payload: evt.payload,
timestamp: BigInt(parsedTs),
fetchedAt: BigInt(evt.fetched_at || Date.now())
},
update: {
payload: evt.payload,
timestamp: BigInt(parsedTs),
fetchedAt: BigInt(evt.fetched_at || Date.now())
}
});
count++;
}
console.log(`[Migration] Successfully migrated ${count} iranwar_events.`);
} catch (e: any) {
console.error(`[Migration] Skipped or failed iranwar_events: ${e.message}`);
}
// 2. Migrate Earthquake
try {
console.log('[Migration] Migrating earthquakes...');
const quakes = db.prepare('SELECT id, payload, source_ts, fetched_at FROM earthquakes').all();
console.log(`[Migration] Found ${quakes.length} earthquakes. Migrating in bulk...`);
const qData = quakes.map((q: any) => ({
id: String(q.id),
payload: q.payload,
sourceTs: BigInt(q.source_ts || Date.now()),
fetchedAt: BigInt(q.fetched_at || Date.now())
}));
if (qData.length > 0) {
await prisma.earthquake.createMany({ data: qData, skipDuplicates: true });
}
console.log(`[Migration] Successfully migrated earthquakes.`);
} catch (e: any) {
console.error(`[Migration] Skipped or failed earthquakes: ${e.message}`);
}
// 3. Migrate Wildfire
try {
console.log('[Migration] Migrating wildfires...');
const fires = db.prepare('SELECT id, payload, source_ts, fetched_at FROM wildfires').all();
console.log(`[Migration] Found ${fires.length} wildfires. Migrating in bulk...`);
const fData = fires.map((f: any) => ({
id: String(f.id),
payload: f.payload,
sourceTs: BigInt(f.source_ts || Date.now()),
fetchedAt: BigInt(f.fetched_at || Date.now())
}));
if (fData.length > 0) {
await prisma.wildfire.createMany({ data: fData, skipDuplicates: true });
}
console.log(`[Migration] Successfully migrated wildfires.`);
} catch (e: any) {
console.error(`[Migration] Skipped or failed wildfires: ${e.message}`);
}
// 4. Migrate MaritimeHistory
try {
console.log('[Migration] Migrating maritime_history...');
const maritime = db.prepare('SELECT mmsi, ts, lat, lon, hdg, spd, fetched_at FROM maritime_history').all();
console.log(`[Migration] Found ${maritime.length} maritime_history records. Migrating in bulk...`);
// Chunk it in case it's huge
const chunkSize = 5000;
for (let i = 0; i < maritime.length; i += chunkSize) {
const chunk = maritime.slice(i, i + chunkSize).map((x: any) => ({
mmsi: String(x.mmsi),
ts: BigInt(x.ts),
lat: x.lat,
lon: x.lon,
heading: x.hdg,
speed: x.spd,
fetchedAt: BigInt(x.fetched_at || Date.now())
}));
await prisma.maritimeHistory.createMany({ data: chunk as any, skipDuplicates: true });
console.log(`[Migration] Migrated ${i + chunk.length}/${maritime.length} maritime_history...`);
}
console.log(`[Migration] Successfully migrated maritime_history.`);
} catch (e: any) {
console.error(`[Migration] Skipped or failed maritime_history: ${e.message}`);
}
// 5. Migrate AviationHistory
try {
console.log('[Migration] Migrating aviation_history...');
const aviation = db.prepare('SELECT icao24, ts, lat, lon, alt, hdg, spd, fetched_at FROM aviation_history').all();
console.log(`[Migration] Found ${aviation.length} aviation_history records. Migrating in bulk...`);
const chunkSize = 5000;
for (let i = 0; i < aviation.length; i += chunkSize) {
const chunk = aviation.slice(i, i + chunkSize).map((x: any) => ({
icao24: String(x.icao24),
ts: BigInt(x.ts),
lat: x.lat,
lon: x.lon,
alt: x.alt,
heading: x.hdg,
speed: x.spd,
fetchedAt: BigInt(x.fetched_at || Date.now())
}));
await prisma.aviationHistory.createMany({ data: chunk as any, skipDuplicates: true });
console.log(`[Migration] Migrated ${i + chunk.length}/${aviation.length} aviation_history...`);
}
console.log(`[Migration] Successfully migrated aviation_history.`);
} catch (e: any) {
console.error(`[Migration] Skipped or failed aviation_history: ${e.message}`);
}
// 6. Migrate MilitaryAviationHistory
try {
console.log('[Migration] Migrating military_aviation_history...');
const maviation = db.prepare('SELECT hex, ts, lat, lon, alt, hdg, spd, fetched_at FROM military_aviation_history').all();
console.log(`[Migration] Found ${maviation.length} military_aviation_history records. Migrating in bulk...`);
const chunkSize = 5000;
for (let i = 0; i < maviation.length; i += chunkSize) {
const chunk = maviation.slice(i, i + chunkSize).map((x: any) => ({
hex: String(x.hex),
ts: BigInt(x.ts),
lat: x.lat,
lon: x.lon,
alt: x.alt,
heading: x.hdg,
speed: x.spd,
fetchedAt: BigInt(x.fetched_at || Date.now())
}));
await prisma.militaryAviationHistory.createMany({ data: chunk as any, skipDuplicates: true });
console.log(`[Migration] Migrated ${i + chunk.length}/${maviation.length} military_aviation_history...`);
}
console.log(`[Migration] Successfully migrated military_aviation_history.`);
} catch (e: any) {
console.error(`[Migration] Skipped or failed military_aviation_history: ${e.message}`);
}
console.log('[Migration] Completed migration from local SQLite to Supabase!');
}
main()
.catch(e => {
console.error(e);
process.exit(1);
})
.finally(async () => {
await prisma.$disconnect();
});
+61
View File
@@ -0,0 +1,61 @@
[Migration] Starting migration from local engine.db to Supabase
[Migration] Reading from SQLite database at: C:\dev\worldwideview\packages\wwv-data-engine\data\engine.db
[Migration] Migrating iranwar_events...
[Migration] Found 242 iranwar_events. Iterating...
[Migration] Skipped or failed iranwar_events:
Invalid `prisma.iranwarEvent.upsert()` invocation in
C:\dev\worldwideview\packages\wwv-data-engine\migrate-sqlite-to-supabase.ts:31:39
28 console.log(`[Migration] Found ${events.length} iranwar_events. Iterating...`);
29 let count = 0;
30 for (const evt of events as any[]) {
→ 31 await prisma.iranwarEvent.upsert({
where: {
eventId: "day-30-evt-0200z"
},
create: {
eventId: "day-30-evt-0200z",
[Migration] Migrating earthquakes...
payload: "{\"event_id\":\"day-30-evt-0200z\",\"type\":\"AIR STRIKE\",\"location\":\"Tehran, Iran\",\"timestamp\":\"2026-03-28T02:00:00.000Z\",\"confidence\":\"Confirmed\",\"event_summary\":\"The combined US-Israeli force conducted precision strikes in Tehran targeting two facilities. The Marine Industries Organization ( ), which oversees 's naval weapons systems including missile-equipped fast boats and drone vessels critical to the blockade, sustained direct hits. A second strike targeted the Physics Department of 's University of Science and Technology ( ), a facility assessed by Western intelligence agencies as linked to nuclear and research programs. The described the strikes as targeting 's capacity to sustain offensive naval and ballistic operations. No casualty figures were released for either site.\",\"source_url\":\"https://www.msn.com/en-in/news/world/sea-of-mourners-gather-in-tehran-for-irgc-commander-alireza-tangsiri-s-funeral/ar-AA1ZVr9D\",\"preview_image\":null,\"_osint_meta\":{\"casualties\":0,\"coordinates\":{\"lat\":35.6892523,\"lng\":51.3896004}}}",
timestamp: "2026-03-28T02:00:00.000Z",
~~~~~~~~~~~~~~~~~~~~~~~~~~
fetchedAt: 1775088300955
},
update: {
payload: "{\"event_id\":\"day-30-evt-0200z\",\"type\":\"AIR STRIKE\",\"location\":\"Tehran, Iran\",\"timestamp\":\"2026-03-28T02:00:00.000Z\",\"confidence\":\"Confirmed\",\"event_summary\":\"The combined US-Israeli force conducted precision strikes in Tehran targeting two facilities. The Marine Industries Organization ( ), which oversees 's naval weapons systems including missile-equipped fast boats and drone vessels critical to the blockade, sustained direct hits. A second strike targeted the Physics Department of 's University of Science and Technology ( ), a facility assessed by Western intelligence agencies as linked to nuclear and research programs. The described the strikes as targeting 's capacity to sustain offensive naval and ballistic operations. No casualty figures were released for either site.\",\"source_url\":\"https://www.msn.com/en-in/news/world/sea-of-mourners-gather-in-tehran-for-irgc-commander-alireza-tangsiri-s-funeral/ar-AA1ZVr9D\",\"preview_image\":null,\"_osint_meta\":{\"casualties\":0,\"coordinates\":{\"lat\":35.6892523,\"lng\":51.3896004}}}",
timestamp: "2026-03-28T02:00:00.000Z",
fetchedAt: 1775088300955
}
})
Argument `timestamp`: Invalid value provided. Expected Int, provided String.
[Migration] Found 145 earthquakes. Migrating in bulk...
[Migration] Skipped or failed earthquakes:
Invalid `prisma.earthquake.createMany()` invocation in
C:\dev\worldwideview\packages\wwv-data-engine\migrate-sqlite-to-supabase.ts:64:37
61 fetchedAt: q.fetched_at
62 }));
63 if (qData.length > 0) {
→ 64 await prisma.earthquake.createMany(
Error occurred during query execution:
ConnectorError(ConnectorError { user_facing_error: None, kind: QueryError(Error { kind: ToSql(2), cause: Some(Error { kind: ConversionError("Unable to fit integer value '1775077787921' into an INT4 (32-bit signed integer)."), original_code: None, original_message: None }) }), transient: false })
[Migration] Migrating wildfires...
[Migration] Found 64649 wildfires. Migrating in bulk...
[Migration] Skipped or failed wildfires:
Invalid `prisma.wildfire.createMany()` invocation in
C:\dev\worldwideview\packages\wwv-data-engine\migrate-sqlite-to-supabase.ts:83:35
80 fetchedAt: f.fetched_at
81 }));
82 if (fData.length > 0) {
→ 83 await prisma.wildfire.createMany(
Error occurred during query execution:
ConnectorError(ConnectorError { user_facing_error: None, kind: QueryError(Error { kind: ToSql(2), cause: Some(Error { kind: ConversionError("Unable to fit integer value '1774915260000' into an INT4 (32-bit signed integer)."), original_code: None, original_message: None }) }), transient: false })
[Migration] Migrating maritime_history...
[Migration] Skipped or failed maritime_history: no such column: heading
[Migration] Migrating aviation_history...
[Migration] Skipped or failed aviation_history: no such column: heading
[Migration] Migrating military_aviation_history...
[Migration] Completed migration from local SQLite to Supabase!
[Migration] Skipped or failed military_aviation_history: no such column: heading
+40
View File
@@ -0,0 +1,40 @@
{
"name": "@worldwideview/wwv-data-engine",
"version": "1.2.1",
"description": "WWV Data Engine - Dual-tier Shared Backend",
"main": "dist/server.js",
"scripts": {
"dev": "tsx watch src/server.ts",
"build": "prisma generate && tsc",
"start": "node dist/server.js",
"prisma:generate": "prisma generate",
"prisma:push": "prisma db push"
},
"dependencies": {
"@fastify/rate-limit": "^10.3.0",
"@fastify/websocket": "^11.2.0",
"@prisma/client": "^6.4.1",
"better-sqlite3": "^12.8.0",
"csv-parse": "^5.6.0",
"dotenv": "^16.4.5",
"fastify": "^5.0.0",
"geoip-lite": "^2.0.1",
"ioredis": "^5.4.1",
"node-cron": "^3.0.3",
"prisma": "^6.4.1",
"sax": "^1.6.0",
"ws": "^8.18.0",
"zod": "^3.23.8"
},
"devDependencies": {
"@types/better-sqlite3": "^7.6.11",
"@types/geoip-lite": "^1.4.4",
"@types/node": "^22.0.0",
"@types/node-cron": "^3.0.11",
"@types/sax": "^1.2.7",
"@types/ws": "^8.5.12",
"ts-node": "^10.9.2",
"tsx": "^4.19.0",
"typescript": "^5.6.2"
}
}
@@ -0,0 +1,85 @@
// This is your Prisma schema file for the WWV Data Engine
// It connects to Supabase to store historical timeline data.
generator client {
provider = "prisma-client-js"
}
datasource db {
provider = "postgresql"
url = env("SUPABASE_DATABASE_URL")
}
model IranwarEvent {
eventId String @id @map("event_id")
payload String // Stored as JSON string to mirror existing SQLite structure
timestamp BigInt
fetchedAt BigInt @map("fetched_at")
@@index([timestamp])
@@map("iranwar_events")
}
model Earthquake {
id String @id
payload String // Stored as JSON string
sourceTs BigInt @map("source_ts")
fetchedAt BigInt @map("fetched_at")
@@index([sourceTs])
@@map("earthquakes")
}
model Wildfire {
id String @id
payload String // Stored as JSON string
sourceTs BigInt @map("source_ts")
fetchedAt BigInt @map("fetched_at")
@@index([sourceTs])
@@map("wildfires")
}
model MaritimeHistory {
mmsi String
ts BigInt
lat Float
lon Float
heading Float? @map("hdg")
speed Float? @map("spd")
fetchedAt BigInt @map("fetched_at")
@@id([mmsi, ts])
@@index([ts])
@@map("maritime_history")
}
model AviationHistory {
icao24 String
ts BigInt
lat Float?
lon Float?
alt Float?
heading Float? @map("hdg")
speed Float? @map("spd")
fetchedAt BigInt @map("fetched_at")
@@id([icao24, ts])
@@index([ts])
@@map("aviation_history")
}
model MilitaryAviationHistory {
hex String
ts BigInt
lat Float?
lon Float?
alt Float?
heading Float? @map("hdg")
speed Float? @map("spd")
fetchedAt BigInt @map("fetched_at")
@@id([hex, ts])
@@index([ts])
@@map("military_aviation_history")
}
+8
View File
@@ -0,0 +1,8 @@
Loaded Prisma config from prisma.config.ts.
Prisma schema loaded from prisma\schema.prisma.
Datasource "db": PostgreSQL database "postgres", schema "public" at "db.oqtfnwsefozpvsoysufm.supabase.co:5432"
Error: P1001: Can't reach database server at `db.oqtfnwsefozpvsoysufm.supabase.co:5432`
Please make sure your database server is running at `db.oqtfnwsefozpvsoysufm.supabase.co:5432`.
@@ -0,0 +1,48 @@
const fs = require('fs');
const path = require('path');
const csvPath = 'C:/dev/worldwideview/artifacts/Events.csv';
const lines = fs.readFileSync(csvPath, 'utf-8').trim().split('\n');
const events = [];
const parseCSVLine = (text) => {
let ret = [], q = false, cv = '';
for (let c of text) {
if (c === '\"') { q = !q; }
else if (c === ',' && !q) { ret.push(cv); cv = ''; }
else { cv += c; }
}
ret.push(cv);
return ret;
};
for(const line of lines) {
const parts = parseCSVLine(line);
if(parts.length < 10) continue;
const [time, date, type, location, casualties, sourceUrl, sourceTitle, summary, eventId, day, articleUrl] = parts;
// time is like '02:00Z', date is like '28-Mar-26'
const isoDate = new Date(`${date} ${time.replace('Z', '')} UTC`).toISOString();
events.push({
event_id: eventId,
type: type,
location: location,
timestamp: isoDate,
confidence: 'Confirmed',
event_summary: summary,
source_url: articleUrl,
preview_image: null,
_osint_meta: {
casualties: parseInt(casualties) || 0,
}
});
}
const outDir = 'C:/dev/worldwideview/packages/wwv-data-engine/seedData';
if (!fs.existsSync(outDir)) {
fs.mkdirSync(outDir, { recursive: true });
}
fs.writeFileSync(path.join(outDir, 'iranwar_seed.json'), JSON.stringify(events, null, 2));
console.log('Saved ' + events.length + ' events to seed.json');
File diff suppressed because it is too large. Load diff
+207
View File
@@ -0,0 +1,207 @@
import Database from 'better-sqlite3';
import path from 'path';
// Define the path for the SQLite database. Note Docker volume mounts to /app/packages/wwv-data-engine/data
const dbPath = process.env.DB_PATH || path.join(__dirname, '..', 'data', 'engine.db');
export const db = new Database(dbPath, {
// Use verbose logging if needed for debugging
// verbose: console.log
});
// Enable Write-Ahead Logging for better concurrent read/write performance
db.pragma('journal_mode = WAL');
db.pragma('synchronous = NORMAL');
db.pragma('busy_timeout = 5000'); // Wait up to 5 seconds if DB is locked
/**
* Initialize all required tables for the different seeders.
* This runs synchronously on boot.
*/
export function initDB() {
console.log(`[DB] Initializing SQLite database at ${dbPath}`);
// IranWarLive table
db.exec(`
CREATE TABLE IF NOT EXISTS iranwar_events (
event_id TEXT PRIMARY KEY,
payload JSON NOT NULL,
timestamp TEXT NOT NULL,
fetched_at INTEGER NOT NULL
)
`);
// Earthquakes table
db.exec(`
CREATE TABLE IF NOT EXISTS earthquakes (
id TEXT PRIMARY KEY,
payload JSON NOT NULL,
source_ts INTEGER NOT NULL,
fetched_at INTEGER NOT NULL
)
`);
// Wildfires table
db.exec(`
CREATE TABLE IF NOT EXISTS wildfires (
id TEXT PRIMARY KEY,
payload JSON NOT NULL,
source_ts INTEGER NOT NULL,
fetched_at INTEGER NOT NULL
)
`);
// Maritime AIS history table
db.exec(`
CREATE TABLE IF NOT EXISTS maritime_history (
mmsi TEXT NOT NULL,
ts INTEGER NOT NULL,
lat REAL NOT NULL,
lon REAL NOT NULL,
hdg REAL,
spd REAL,
fetched_at INTEGER NOT NULL,
PRIMARY KEY (mmsi, ts)
)
`);
// Index for fast maritime history lookups by MMSI + time range
db.exec(`
CREATE INDEX IF NOT EXISTS idx_maritime_history_mmsi_ts ON maritime_history(mmsi, ts);
`);
// Index for time-range-only queries (playback mode)
db.exec(`
CREATE INDEX IF NOT EXISTS idx_maritime_history_ts ON maritime_history(ts);
`);
// Aviation history table
db.exec(`
CREATE TABLE IF NOT EXISTS aviation_history (
icao24 TEXT NOT NULL,
ts INTEGER NOT NULL,
lat REAL,
lon REAL,
alt REAL,
hdg REAL,
spd REAL,
fetched_at INTEGER NOT NULL,
PRIMARY KEY (icao24, ts)
)
`);
// Index for fast aviation history lookups by ICAO24 + time range
db.exec(`
CREATE INDEX IF NOT EXISTS idx_aviation_history_icao24_ts ON aviation_history(icao24, ts);
`);
// Index for time-range-only queries (playback mode)
db.exec(`
CREATE INDEX IF NOT EXISTS idx_aviation_history_ts ON aviation_history(ts);
`);
// Military Aviation history table
db.exec(`
CREATE TABLE IF NOT EXISTS military_aviation_history (
hex TEXT NOT NULL,
ts INTEGER NOT NULL,
lat REAL,
lon REAL,
alt REAL,
hdg REAL,
spd REAL,
fetched_at INTEGER NOT NULL,
PRIMARY KEY (hex, ts)
)
`);
// Index for fast military aviation history lookups by hex + time range
db.exec(`
CREATE INDEX IF NOT EXISTS idx_military_aviation_history_hex_ts ON military_aviation_history(hex, ts);
`);
// Index for time-range-only queries (playback mode)
db.exec(`
CREATE INDEX IF NOT EXISTS idx_military_aviation_history_ts ON military_aviation_history(ts);
`);
// GPS Jamming daily interference map
db.exec(`
CREATE TABLE IF NOT EXISTS gps_jamming (
id TEXT PRIMARY KEY,
payload JSON NOT NULL,
source_ts INTEGER NOT NULL,
fetched_at INTEGER NOT NULL
)
`);
// Conflict Events (ACLED) DB table
db.exec(`
CREATE TABLE IF NOT EXISTS conflict_events (
id TEXT PRIMARY KEY,
payload JSON NOT NULL,
source_ts INTEGER NOT NULL,
fetched_at INTEGER NOT NULL
)
`);
// Civil Unrest DB table
db.exec(`
CREATE TABLE IF NOT EXISTS civil_unrest (
id TEXT PRIMARY KEY,
payload JSON NOT NULL,
source_ts INTEGER NOT NULL,
fetched_at INTEGER NOT NULL
)
`);
// Cyber Attacks table
db.exec(`
CREATE TABLE IF NOT EXISTS cyber_attacks (
id TEXT PRIMARY KEY,
payload JSON NOT NULL,
source_ts INTEGER NOT NULL,
fetched_at INTEGER NOT NULL
)
`);
// Index for cyber attacks time-range queries (playback mode)
db.exec(`
CREATE INDEX IF NOT EXISTS idx_cyber_attacks_source_ts ON cyber_attacks(source_ts);
`);
// Sanctions table
db.exec(`
CREATE TABLE IF NOT EXISTS sanctions (
id TEXT PRIMARY KEY,
payload JSON NOT NULL,
source_ts INTEGER NOT NULL,
fetched_at INTEGER NOT NULL
)
`);
console.log('[DB] All tables initialized successfully.');
}
/**
* Prune history rows older than the retention period.
* Runs periodically to prevent unbounded table growth.
*/
const RETENTION_HOURS = 24;
export function pruneHistoryTables() {
const cutoff = Math.floor(Date.now() / 1000) - RETENTION_HOURS * 3600;
const tables = [
'aviation_history',
'military_aviation_history',
'maritime_history',
];
for (const table of tables) {
const result = db.prepare(`DELETE FROM ${table} WHERE ts < ?`).run(cutoff);
if (result.changes > 0) {
console.log(`[DB] Pruned ${result.changes} rows from ${table}`);
}
}
}
+24
View File
@@ -0,0 +1,24 @@
import geoip from 'geoip-lite';
export interface GeoLocation {
lat: number;
lon: number;
country: string;
city: string;
}
/**
* Geolocate an IPv4 address using the local geoip-lite database.
* Returns null for private/unresolvable IPs.
*/
export function geolocateIp(ip: string): GeoLocation | null {
const lookup = geoip.lookup(ip);
if (!lookup || !lookup.ll) return null;
return {
lat: lookup.ll[0],
lon: lookup.ll[1],
country: lookup.country || 'Unknown',
city: lookup.city || 'Unknown',
};
}
+12
View File
@@ -0,0 +1,12 @@
import { PrismaClient } from '@prisma/client';
declare global {
// eslint-disable-next-line no-var
var prismaDataEngine: PrismaClient | undefined;
}
export const prisma =
globalThis.prismaDataEngine ||
new PrismaClient();
if (process.env.NODE_ENV !== 'production') globalThis.prismaDataEngine = prisma;
+96
View File
@@ -0,0 +1,96 @@
import Redis from 'ioredis';
import dotenv from 'dotenv';
import path from 'path';
import zlib from 'zlib';
dotenv.config({ path: path.resolve(process.cwd(), '../../.env.local') });
dotenv.config({ path: path.resolve(process.cwd(), '../../.env') });
// ioredis gracefully handles standard redis:// as well as rediss:// (TLS, used by Upstash)
const redisUrl = process.env.REDIS_URL || 'redis://localhost:6379';
if (redisUrl.includes('upstash.io') && redisUrl.startsWith('redis://')) {
console.error('\n\x1b[31m[CRITICAL CONFIG ERROR]\x1b[0m 🚨 You are connecting to Upstash without TLS.');
console.error('Upstash requires the rediss:// protocol. Please update your REDIS_URL in .env.local to start with rediss:// instead of redis://\n');
}
console.log(`[Redis] Connecting to ${redisUrl.replace(/:[^:@]+@/, ':***@')} ...`);
export const redis = new Redis(redisUrl, {
// Common reconnect strategy
retryStrategy(times) {
const delay = Math.min(times * 50, 2000);
return delay;
},
maxRetriesPerRequest: 3,
});
redis.on('error', (err) => {
console.error('[Redis] Connection Error against URL:', redisUrl.replace(/:[^:@]+@/, ':***@'));
console.error('[Redis] Error Object:', err);
});
redis.on('ready', () => {
console.log('[Redis] Connected and ready.');
});
import { broadcastPluginData } from './websocket';
const lastSnapshotTimes = new Map<string, number>();
const SNAPSHOT_THROTTLE_MS = 5 * 60 * 1000; // 5 minutes
/**
* Convenience method to write a JSON payload to Redis with an expiration.
* Writes are throttled to save Redis requests, but websockets are always broadcasted.
*/
export async function setLiveSnapshot(source: string, payload: any, ttlSeconds: number) {
try {
// 1. ALWAYS broadcast newly updated entities to any active WebSocket subscribers
// The data pipeline relies on this for high-frequency HUD updates.
broadcastPluginData(source, payload);
// 2. Throttle Redis snapshots to prevent blowing past 500K max request limits (e.g. Upstash)
const now = Date.now();
const lastTime = lastSnapshotTimes.get(source) || 0;
if (now - lastTime < SNAPSHOT_THROTTLE_MS) {
return; // Skip Redis write
}
lastSnapshotTimes.set(source, now);
const key = `data:${source}:live`;
const jsonStr = JSON.stringify(payload);
// Compress JSON strings to drastically reduce Upstash payload size
const compressed = zlib.gzipSync(Buffer.from(jsonStr, 'utf-8'));
await redis.set(key, compressed as any, 'EX', ttlSeconds);
// Also save a metadata key so healthcheck can verify
await redis.set(`meta:${source}:last_run`, Date.now().toString(), 'EX', ttlSeconds * 2);
console.log(`[Redis] Snapshot saved to Redis for ${source} (${(compressed.length / 1024).toFixed(2)} KB)`);
} catch (error) {
console.error(`[Redis] Failed to snapshot ${source}:`, error);
}
}
/**
* Convenience method to read a JSON payload from Redis.
*/
export async function getLiveSnapshot(source: string) {
const key = `data:${source}:live`;
try {
// We must use getBuffer natively in ioredis to prevent it from coercing raw bytes to a utf8 string
const data = await redis.getBuffer(key);
if (!data) return null;
try {
const decompressed = zlib.unzipSync(data);
return JSON.parse(decompressed.toString('utf-8'));
} catch {
// Fallback if data was stored as plain string before compression was introduced
return JSON.parse(data.toString('utf-8'));
}
} catch (error) {
console.error(`[Redis] Failed to get live snapshot ${source}:`, error);
return null;
}
}
@@ -0,0 +1,69 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
fastify.get('/data/aviation', async (request: any, reply) => {
try {
const { lookback, time } = request.query;
// Historical playback mode snapshot
if (time && typeof time === 'string') {
const targetTs = Math.floor(parseInt(time, 10) / 1000);
const historyQuery = db.prepare(`
SELECT icao24, ts, lat, lon, hdg, spd, alt
FROM aviation_history
WHERE ts BETWEEN @start AND @end
`);
const historyRows = historyQuery.all({
start: targetTs - 60,
end: targetTs + 60,
}) as any[];
const closest = new Map();
for (const r of historyRows) {
const prev = closest.get(r.icao24);
if (!prev || Math.abs(r.ts - targetTs) < Math.abs(prev.ts - targetTs)) {
closest.set(r.icao24, { ...r, on_ground: r.alt <= 0 });
}
}
return {
source: 'aviation',
fetchedAt: new Date().toISOString(),
lookbackSeconds: 0,
items: Array.from(closest.values()),
totalCount: closest.size,
};
}
// Parse lookback (e.g., "15m" -> 900s, "1h" -> 3600s)
let lookbackSeconds = 0;
if (lookback && typeof lookback === 'string') {
const match = lookback.match(/^(\d+)([hm])$/);
if (match) {
const val = parseInt(match[1], 10);
lookbackSeconds = match[2] === 'h' ? val * 3600 : val * 60;
}
}
// Get live fleet from Redis and filter by freshness
const fleetObj = (await getLiveSnapshot('aviation')) || {};
const activeFleet = Object.values(fleetObj) as any[];
const nowTs = Math.floor(Date.now() / 1000);
const maxAge = lookbackSeconds > 0 ? lookbackSeconds : 3600;
const items = activeFleet.filter(
(plane) => nowTs - plane.last_updated <= maxAge
);
return {
source: 'aviation',
fetchedAt: new Date().toISOString(),
lookbackSeconds: lookbackSeconds || null,
items,
totalCount: items.length,
};
} catch (err: any) {
console.error('[Aviation Route] ERROR:', err?.message || err);
reply.status(500).send({ error: 'Internal error', message: err?.message });
}
});
@@ -0,0 +1,28 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
const getHistoryQuery = db.prepare('SELECT payload FROM civil_unrest WHERE source_ts >= @start AND source_ts <= @end ORDER BY source_ts DESC');
fastify.get('/data/civil_unrest', async (request, reply) => {
const liveData = await getLiveSnapshot('civil_unrest');
if (liveData) {
return { data: liveData };
}
return { data: [] };
});
fastify.get('/data/civil_unrest/history', async (request: any, reply) => {
const { start, end } = request.query;
if (!start || !end) {
return reply.status(400).send({ error: 'Missing start or end query params (Unix timestamps in ms)' });
}
const rows = getHistoryQuery.all({ start: parseInt(start, 10), end: parseInt(end, 10) }) as { payload: string }[];
const historyItems = rows.map(row => JSON.parse(row.payload));
return {
source: "civil_unrest",
timeRange: { start: parseInt(start, 10), end: parseInt(end, 10) },
items: historyItems,
totalCount: historyItems.length
};
});
@@ -0,0 +1,28 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
const getHistoryQuery = db.prepare('SELECT payload FROM conflict_events WHERE source_ts >= @start AND source_ts <= @end ORDER BY source_ts DESC');
fastify.get('/data/conflict_events', async (request, reply) => {
const liveData = await getLiveSnapshot('conflict_events');
if (liveData) {
return { data: liveData };
}
return { data: [] };
});
fastify.get('/data/conflict_events/history', async (request: any, reply) => {
const { start, end } = request.query;
if (!start || !end) {
return reply.status(400).send({ error: 'Missing start or end query params (Unix timestamps in ms)' });
}
const rows = getHistoryQuery.all({ start: parseInt(start, 10), end: parseInt(end, 10) }) as { payload: string }[];
const historyItems = rows.map(row => JSON.parse(row.payload));
return {
source: "conflict_events",
timeRange: { start: parseInt(start, 10), end: parseInt(end, 10) },
items: historyItems,
totalCount: historyItems.length
};
});
@@ -0,0 +1,45 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
const getHistoryQuery = db.prepare(
'SELECT payload FROM cyber_attacks WHERE source_ts >= @start AND source_ts <= @end ORDER BY source_ts DESC'
);
// Standard live endpoint → returns Redis snapshot
fastify.get('/data/cyber_attacks', async (request, reply) => {
const liveData = await getLiveSnapshot('cyber_attacks');
if (liveData) {
return liveData;
}
return {
source: 'cyber_attacks',
fetchedAt: null,
items: [],
totalCount: 0,
};
});
// History endpoint → queries SQLite
fastify.get('/data/cyber_attacks/history', async (request: any, reply) => {
const { start, end } = request.query;
if (!start || !end) {
return reply
.status(400)
.send({ error: 'Missing start or end query params (Unix timestamps in ms)' });
}
const rows = getHistoryQuery.all({
start: parseInt(start, 10),
end: parseInt(end, 10),
}) as { payload: string }[];
const historyItems = rows.map((row) => JSON.parse(row.payload));
return {
source: 'cyber_attacks',
timeRange: { start: parseInt(start, 10), end: parseInt(end, 10) },
items: historyItems,
totalCount: historyItems.length,
};
});
@@ -0,0 +1,38 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
const getHistoryQuery = db.prepare('SELECT payload FROM earthquakes WHERE source_ts >= @start AND source_ts <= @end ORDER BY source_ts DESC');
// Standard live endpoint -> returns Redis snapshot
fastify.get('/data/earthquakes', async (request, reply) => {
const liveData = await getLiveSnapshot('earthquakes');
if (liveData) {
return liveData;
}
return {
source: "earthquakes",
fetchedAt: null,
items: [],
totalCount: 0
};
});
// Full history endpoint -> queries SQLite
fastify.get('/data/earthquakes/history', async (request: any, reply) => {
const { start, end } = request.query;
if (!start || !end) {
return reply.status(400).send({ error: 'Missing start or end query params (Unix timestamps in ms)' });
}
const rows = getHistoryQuery.all({ start: parseInt(start, 10), end: parseInt(end, 10) }) as { payload: string }[];
const historyItems = rows.map(row => JSON.parse(row.payload));
return {
source: "earthquakes",
timeRange: { start: parseInt(start, 10), end: parseInt(end, 10) },
items: historyItems,
totalCount: historyItems.length
};
});
@@ -0,0 +1,33 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
const getHistoryQuery = db.prepare('SELECT payload FROM gps_jamming WHERE source_ts >= @start AND source_ts <= @end');
fastify.get('/data/gps_jamming', async (request, reply) => {
const liveData = await getLiveSnapshot('gps_jamming');
if (liveData) {
return liveData;
}
return {
source: "gps_jamming",
fetchedAt: null,
items: [],
totalCount: 0
};
});
fastify.get('/data/gps_jamming/history', async (request: any, reply) => {
const { start, end } = request.query;
if (!start || !end) {
return reply.status(400).send({ error: 'Missing start or end query params (Unix timestamps in ms)' });
}
const rows = getHistoryQuery.all({ start: parseInt(start, 10), end: parseInt(end, 10) }) as { payload: string }[];
const historyItems = rows.map(row => JSON.parse(row.payload));
return {
source: "gps_jamming",
timeRange: { start: parseInt(start, 10), end: parseInt(end, 10) },
items: historyItems,
totalCount: historyItems.length
};
});
@@ -0,0 +1,13 @@
import './iranwarlive';
import './earthquakes';
import './wildfires';
import './maritime';
import './aviation';
import './military-aviation';
import './satellite';
import './gpsjam';
import './conflictEvents';
import './civilUnrest';
import './cyberAttacks';
import './sanctions';
import './surveillanceSat';
@@ -0,0 +1,37 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
const getAllEventsQuery = db.prepare('SELECT payload FROM iranwar_events ORDER BY timestamp DESC');
// Standard live endpoint -> returns Redis snapshot
fastify.get('/data/iranwarlive', async (request, reply) => {
const liveData = await getLiveSnapshot('iranwarlive');
if (liveData) {
return liveData;
}
// Fallback to SQLite if Redis is empty/cleared
const rows = getAllEventsQuery.all() as { payload: string }[];
const history = rows.map(row => JSON.parse(row.payload));
return {
source: "iranwarlive",
fetchedAt: new Date().toISOString(),
items: history
};
});
// Full history endpoint -> queries SQLite
fastify.get('/data/iranwarlive/history', async (request, reply) => {
// Iran war live has small enough history that we can return it all.
// In a massive set, we would use query params: ?start=ts&end=ts
const rows = getAllEventsQuery.all() as { payload: string }[];
const history = rows.map(row => JSON.parse(row.payload));
return {
version: "2.0",
source: "iranwarlive",
last_updated: new Date().toISOString(),
items: history
};
});
@@ -0,0 +1,96 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
fastify.get('/data/maritime', async (request: any, reply) => {
try {
const { lookback, time } = request.query;
// Historical playback mode snapshot
if (time && typeof time === 'string') {
const targetTs = Math.floor(parseInt(time, 10) / 1000);
const historyQuery = db.prepare(`
SELECT mmsi, ts, lat, lon, hdg, spd
FROM maritime_history
WHERE ts BETWEEN @start AND @end
`);
const historyRows = historyQuery.all({
start: targetTs - 60,
end: targetTs + 60,
}) as any[];
const closest = new Map();
for (const r of historyRows) {
const prev = closest.get(r.mmsi);
if (!prev || Math.abs(r.ts - targetTs) < Math.abs(prev.ts - targetTs)) {
closest.set(r.mmsi, r);
}
}
return {
source: 'maritime',
fetchedAt: new Date().toISOString(),
lookbackSeconds: 0,
items: Array.from(closest.values()),
totalCount: closest.size,
};
}
// Parse lookback (e.g., "6h" -> seconds)
let lookbackSeconds = 0;
if (lookback && typeof lookback === 'string') {
const match = lookback.match(/^(\d+)([hm])$/);
if (match) {
const val = parseInt(match[1], 10);
lookbackSeconds = match[2] === 'h' ? val * 3600 : val * 60;
}
}
// Get live fleet from Redis and filter by freshness
const fleetObj = (await getLiveSnapshot('maritime')) || {};
const activeFleet = Object.values(fleetObj) as any[];
const nowTs = Math.floor(Date.now() / 1000);
const maxAge = lookbackSeconds > 0 ? lookbackSeconds : 3600;
const items = activeFleet.filter(
(ship) => nowTs - ship.last_updated <= maxAge
);
// If lookback was requested, grab history points from SQLite
if (lookbackSeconds > 0 && items.length > 0) {
const historyQuery = db.prepare(`
SELECT mmsi, ts, lat, lon
FROM maritime_history
WHERE ts >= @startTs
`);
const allHistory = historyQuery.all({ startTs: nowTs - lookbackSeconds }) as any[];
const historyMap = new Map<string, any[]>();
for (const row of allHistory) {
if (!historyMap.has(row.mmsi)) historyMap.set(row.mmsi, []);
historyMap.get(row.mmsi)!.push({ lat: row.lat, lon: row.lon, ts: row.ts });
}
for (const ship of items) {
const pts = historyMap.get(ship.mmsi);
if (pts && pts.length > 0) {
// Sort chronologically ascending
pts.sort((a, b) => a.ts - b.ts);
ship.history = pts;
} else {
ship.history = [];
}
}
}
return {
source: 'maritime',
fetchedAt: new Date().toISOString(),
lookbackSeconds: lookbackSeconds || null,
items,
totalCount: items.length,
};
} catch (err: any) {
console.error('[Maritime Route] ERROR:', err?.message || err);
reply.status(500).send({ error: 'Internal error', message: err?.message });
}
});
@@ -0,0 +1,69 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
fastify.get('/data/military-aviation', async (request: any, reply) => {
try {
const { lookback, time } = request.query;
// Historical playback mode snapshot
if (time && typeof time === 'string') {
const targetTs = Math.floor(parseInt(time, 10) / 1000);
const historyQuery = db.prepare(`
SELECT hex, ts, lat, lon, hdg, spd, alt
FROM military_aviation_history
WHERE ts BETWEEN @start AND @end
`);
const historyRows = historyQuery.all({
start: targetTs - 60,
end: targetTs + 60,
}) as any[];
const closest = new Map();
for (const r of historyRows) {
const prev = closest.get(r.hex);
if (!prev || Math.abs(r.ts - targetTs) < Math.abs(prev.ts - targetTs)) {
closest.set(r.hex, { ...r, on_ground: r.alt <= 0 });
}
}
return {
source: 'military-aviation',
fetchedAt: new Date().toISOString(),
lookbackSeconds: 0,
ac: Array.from(closest.values()),
totalCount: closest.size,
};
}
// Parse lookback (e.g., "15m" -> 900s, "1h" -> 3600s)
let lookbackSeconds = 0;
if (lookback && typeof lookback === 'string') {
const match = lookback.match(/^(\d+)([hm])$/);
if (match) {
const val = parseInt(match[1], 10);
lookbackSeconds = match[2] === 'h' ? val * 3600 : val * 60;
}
}
// Get live fleet from Redis and filter by freshness
const fleetObj = (await getLiveSnapshot('military-aviation')) || {};
const activeFleet = Object.values(fleetObj) as any[];
const nowTs = Math.floor(Date.now() / 1000);
const maxAge = lookbackSeconds > 0 ? lookbackSeconds : 3600;
const items = activeFleet.filter(
(plane) => nowTs - plane.last_updated <= maxAge
);
return {
source: 'military-aviation',
fetchedAt: new Date().toISOString(),
lookbackSeconds: lookbackSeconds || null,
ac: items,
totalCount: items.length,
};
} catch (err: any) {
console.error('[MilitaryAviation Route] ERROR:', err?.message || err);
reply.status(500).send({ error: 'Internal error', message: err?.message });
}
});
@@ -0,0 +1,15 @@
import { fastify } from '../server';
import { getLiveSnapshot } from '../redis';
// Sanctions are Redis-only (no SQLite table) — live data only
fastify.get('/data/sanctions', async (request, reply) => {
const liveData = await getLiveSnapshot('sanctions');
if (liveData) {
return liveData;
}
return {
id: 'sanctions-live',
timestamp: null,
items: []
};
});
@@ -0,0 +1,54 @@
import { fastify } from '../server';
import { getLiveSnapshot } from '../redis';
import { globalsTLECache, propagateAll, DEFAULT_GROUPS } from '../seeders/satellite';
fastify.get('/data/satellite', async (request: any, reply) => {
const { lookback, time, group } = request.query;
const targetGroups = group ? [group as string] : DEFAULT_GROUPS;
// Historical playback mode snapshot using TLE on the fly
if (time && typeof time === 'string') {
const targetTime = new Date(parseInt(time, 10));
let items: any[] = [];
const seen = new Set<number>();
for (const g of targetGroups) {
const records = globalsTLECache.get(g);
if (!records) continue;
const positions = propagateAll(records, targetTime, g);
for (const p of positions) {
if (!seen.has(p.noradId)) {
items.push(p);
seen.add(p.noradId);
}
}
}
return {
source: "satellite",
fetchedAt: new Date().toISOString(),
lookbackSeconds: 0,
items: items,
totalCount: items.length
};
}
// 1. Get hot fleet from Redis for current time
const fleetObj = await getLiveSnapshot('satellite') || {};
let items = Object.values(fleetObj) as any[];
if (group) {
items = items.filter(s => s.group === group);
}
return {
source: "satellite",
fetchedAt: new Date().toISOString(),
lookbackSeconds: null,
items,
totalCount: items.length
};
});
@@ -0,0 +1,11 @@
import { fastify } from '../server';
import { getLiveSnapshot } from '../redis';
// Surveillance Satellites split route
fastify.get('/data/surveillance_satellites', async (request, reply) => {
const liveData = await getLiveSnapshot('surveillance_satellites');
if (liveData) {
return { satellites: Object.values(liveData) };
}
return { satellites: [] };
});
@@ -0,0 +1,38 @@
import { fastify } from '../server';
import { db } from '../db';
import { getLiveSnapshot } from '../redis';
const getHistoryQuery = db.prepare('SELECT payload FROM wildfires WHERE source_ts >= @start AND source_ts <= @end');
// Standard live endpoint -> returns Redis snapshot
fastify.get('/data/wildfires', async (request, reply) => {
const liveData = await getLiveSnapshot('wildfires');
if (liveData) {
return liveData;
}
return {
source: "wildfires",
fetchedAt: null,
items: [],
totalCount: 0
};
});
// Full history endpoint -> queries SQLite
fastify.get('/data/wildfires/history', async (request: any, reply) => {
const { start, end } = request.query;
if (!start || !end) {
return reply.status(400).send({ error: 'Missing start or end query params (Unix timestamps in ms)' });
}
const rows = getHistoryQuery.all({ start: parseInt(start, 10), end: parseInt(end, 10) }) as { payload: string }[];
const historyItems = rows.map(row => JSON.parse(row.payload));
return {
source: "wildfires",
timeRange: { start: parseInt(start, 10), end: parseInt(end, 10) },
items: historyItems,
totalCount: historyItems.length
};
});
+70
View File
@@ -0,0 +1,70 @@
import cron from 'node-cron';
import { pruneHistoryTables } from './db';
// Define the interface for a seeder definition
export interface SeederDefinition {
name: string;
cron?: string; // Optional: Cron expression if it runs on a schedule
fn?: () => Promise<void>; // Optional: Function to run on the cron schedule
init?: () => void; // Optional: Initialization function (e.g., for websockets)
}
// Registry to hold all registered seeders
let registeredSeeders: SeederDefinition[] = [];
// Registry to track the last run time of each cron seeder
export const seederStatus: Record<string, number | null> = {};
/**
* Register a seeder to be scheduled when the engine boots.
*/
export function registerSeeder(seeder: SeederDefinition) {
registeredSeeders.push(seeder);
if (seeder.cron) {
seederStatus[seeder.name] = null;
}
}
/**
* Start the scheduler. Initializes websocket listeners and registers cron jobs.
*/
export function startScheduler() {
console.log('[Scheduler] Starting data engine scheduler...');
for (const seeder of registeredSeeders) {
// 1. Run init handlers (like websocket listeners)
if (seeder.init) {
console.log(`[Scheduler] Initializing persistent seeder: ${seeder.name}`);
seeder.init();
}
// 2. Schedule cron jobs
if (seeder.cron && seeder.fn) {
console.log(`[Scheduler] Scheduling cron seeder: ${seeder.name} (${seeder.cron})`);
cron.schedule(seeder.cron, async () => {
try {
console.log(`[Scheduler] Running seeder: ${seeder.name} ...`);
await seeder.fn!();
seederStatus[seeder.name] = Date.now();
} catch (error: any) {
console.error(`[Scheduler] Seeder ${seeder.name} failed:`, error.message);
}
});
// Kick off the first run immediately for cron jobs
console.log(`[Scheduler] Kickstarting initial run for ${seeder.name}...`);
seeder.fn().then(() => {
seederStatus[seeder.name] = Date.now();
}).catch((err) => {
console.error(`[Scheduler] Initial run for ${seeder.name} failed:`, err.message);
});
}
}
// Data retention: prune old history rows every hour
cron.schedule('0 * * * *', () => {
console.log('[Scheduler] Running data retention pruning...');
pruneHistoryTables();
});
}
@@ -0,0 +1,102 @@
import fs from 'fs';
import path from 'path';
import * as cheerio from 'cheerio';
const seedPath = path.join(__dirname, '..', '..', 'data', 'fallback', 'iranwar_seed.json');
async function delay(ms: number) {
return new Promise(resolve => setTimeout(resolve, ms));
}
async function extractMedia(url: string): Promise<{img: string | null, vid: string | null, realUrl: string | null}> {
try {
const res = await fetch(url, {
headers: {
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
"Accept-Language": "en-US,en;q=0.5"
},
signal: AbortSignal.timeout(10000)
});
const text = await res.text();
const $ = cheerio.load(text);
let realUrl = res.url;
// Sometimes Bing wraps in a redirect page
if ($('noscript').text().includes('refresh')) {
const redirectMatch = $('noscript').html()?.match(/URL=([^"']+)/i);
if (redirectMatch && redirectMatch[1]) {
const redir = redirectMatch[1].replace(/&amp;/g, '&');
try {
const redirRes = await fetch(redir, { headers: { "User-Agent": "Mozilla/5.0" }, signal: AbortSignal.timeout(10000) });
const redirHtml = await redirRes.text();
const $2 = cheerio.load(redirHtml);
realUrl = redirRes.url;
return { ...parseMetas($2, realUrl), realUrl };
} catch(e) {}
}
}
return { ...parseMetas($, realUrl), realUrl };
} catch {
return { img: null, vid: null, realUrl: null };
}
}
function parseMetas($: cheerio.CheerioAPI, source: string) {
const img = $('meta[property="og:image"]').attr('content') || $('meta[name="twitter:image"]').attr('content') || null;
const vid = $('meta[property="og:video:url"]').attr('content') || $('meta[property="og:video"]').attr('content') || null;
return { img, vid };
}
async function run() {
console.log("Loading existing seed...");
if (!fs.existsSync(seedPath)) {
console.error("Seed not found!");
return;
}
const events: any[] = JSON.parse(fs.readFileSync(seedPath, 'utf8'));
let count = 0;
for (const event of events) {
const isSearchable = !["POSTURING", "INTERCEPTION", "AIRSPACE CLOSED"].includes(event.type?.toUpperCase() || "");
if (isSearchable && event.location && event.type) {
console.log(`[Hydrate] Searching Bing News for: ${event.type} ${event.location}`);
const query = encodeURIComponent(`${event.type} ${event.location} Iran Israel conflict`);
try {
const searchRes = await fetch(`https://www.bing.com/news/search?q=${query}&format=rss`, {
headers: { "User-Agent": "Mozilla/5.0" },
signal: AbortSignal.timeout(5000)
});
if (searchRes.ok) {
const xml = await searchRes.text();
const $ = cheerio.load(xml, { xmlMode: true });
const items = $('item');
if (items.length > 0) {
const articleUrl = $(items[0]).find('link').text();
console.log(` -> Found article string: ${articleUrl.substring(0, 50)}...`);
const media = await extractMedia(articleUrl);
event.source_url = media.realUrl || articleUrl;
if (media.vid) event.preview_video = media.vid;
if (media.img) event.preview_image = media.img;
count++;
}
}
} catch (err: any) {
console.warn(` -> Search failed: ${err.message}`);
}
fs.writeFileSync(seedPath, JSON.stringify(events, null, 2));
await delay(500);
}
}
console.log(`Extraction complete. Modified ${count} events.`);
}
run().catch(console.error);
@@ -0,0 +1,55 @@
export async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3, delayMs = 1000): Promise<T> {
let lastErr: Error | undefined;
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
return await fn();
} catch (err: any) {
lastErr = err;
if (attempt < maxRetries) {
const wait = delayMs * Math.pow(2, attempt); // Exponential backoff
console.warn(`[Retry] Attempt ${attempt + 1}/${maxRetries} failed: ${err.message}. Waiting ${wait}ms...`);
await new Promise(r => setTimeout(r, wait));
}
}
}
throw lastErr;
}
export async function fetchWithTimeout(url: string, options: RequestInit = {}, timeoutMs = 15000): Promise<Response> {
const controller = new AbortController();
const id = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(url, {
...options,
signal: controller.signal,
});
if (!response.ok) {
throw new Error(`HTTP ${response.status} - ${response.statusText}`);
}
return response;
} finally {
clearTimeout(id);
}
}
/**
* Calculates distance in Kilometers between two coordinates.
* Useful for filtering events by proximity (e.g., nuclear test sites).
*/
export function haversineKm(lat1: number, lon1: number, lat2: number, lon2: number): number {
const R = 6371; // km
const dLat = (lat2 - lat1) * Math.PI / 180;
const dLon = (lon2 - lon1) * Math.PI / 180;
const a =
Math.sin(dLat/2) * Math.sin(dLat/2) +
Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
Math.sin(dLon/2) * Math.sin(dLon/2);
const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
return R * c;
}
export const CHROME_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36';
export function sleep(ms: number) {
return new Promise(r => setTimeout(r, ms));
}
@@ -0,0 +1,279 @@
import cron from 'node-cron';
import { db } from '../db';
import { redis, setLiveSnapshot } from '../redis';
import { registerSeeder } from '../scheduler';
const OPENSKY_TOKEN_URL = "https://auth.opensky-network.org/auth/realms/opensky-network/protocol/openid-connect/token";
const OPENSKY_DATA_URL = "https://opensky-network.org/api/states/all";
const ROTATION_THRESHOLD = 50;
const POLLING_INTERVAL_MS = 5000;
const FLUSH_INTERVAL_MS = 5000;
let messageBuffer: any[] = [];
interface OpenSkyCredential {
clientId: string;
clientSecret: string;
accessToken: string | null;
tokenExpiry: number;
creditsRemaining: number | null;
exhausted: boolean;
}
const pool = {
_openskyPool: [] as OpenSkyCredential[],
_openskyActiveIdx: 0,
_lastResetTime: Date.now()
};
function initCredentialPool(): void {
if (pool._openskyPool.length > 0) return;
const creds: OpenSkyCredential[] = [];
const raw = process.env.OPENSKY_CREDENTIALS;
if (raw) {
for (const pair of raw.split(",")) {
const trimmed = pair.trim();
const colonIdx = trimmed.indexOf(":");
if (colonIdx === -1) continue;
const clientId = trimmed.slice(0, colonIdx);
const clientSecret = trimmed.slice(colonIdx + 1);
if (clientId && clientSecret) {
creds.push({ clientId, clientSecret, accessToken: null, tokenExpiry: 0, creditsRemaining: null, exhausted: false });
}
}
}
if (creds.length === 0) {
// Fallback
const clientId = process.env.OPENSKY_CLIENTID;
const clientSecret = process.env.OPENSKY_CLIENTSECRET;
if (clientId && clientSecret) {
creds.push({ clientId, clientSecret, accessToken: null, tokenExpiry: 0, creditsRemaining: null, exhausted: false });
}
}
pool._openskyPool = creds;
pool._openskyActiveIdx = 0;
pool._lastResetTime = Date.now();
console.log(`[Aviation] Initialised pool with ${creds.length} credential(s).`);
}
/**
* Resets all credentials in the pool to non-exhausted state.
*/
function resetCredentialPool(): void {
console.log('[Aviation] Resetting credential pool exhaustion flags...');
for (const cred of pool._openskyPool) {
cred.exhausted = false;
cred.creditsRemaining = null;
}
pool._openskyActiveIdx = 0;
pool._lastResetTime = Date.now();
}
function getActiveCredential(): OpenSkyCredential | null {
const creds = pool._openskyPool;
if (!creds || creds.length === 0) return null;
const current = creds[pool._openskyActiveIdx];
if (current && !current.exhausted) return current;
for (let i = 0; i < creds.length; i++) {
if (!creds[i].exhausted) {
pool._openskyActiveIdx = i;
console.log(`[Aviation] Rotated → now using credential ${i + 1}/${creds.length}: ${creds[i].clientId}`);
return creds[i];
}
}
// Emergency Reset: If all are exhausted, but it's been > 12 hours since last reset,
// try resetting everything once before giving up.
const twelveHoursMs = 12 * 60 * 60 * 1000;
if (Date.now() - pool._lastResetTime > twelveHoursMs) {
console.warn(`[Aviation] Emergency Reset: All credentials exhausted, but last reset was > 12h ago. Attempting pool reset.`);
resetCredentialPool();
return getActiveCredential();
}
console.warn(`[Aviation] All ${creds.length} credentials exhausted.`);
return null;
}
function rotateCredential(): void {
const current = pool._openskyPool[pool._openskyActiveIdx];
if (current) current.exhausted = true;
getActiveCredential();
}
async function fetchTokenForCredential(cred: OpenSkyCredential): Promise<string | null> {
const now = Date.now();
if (cred.accessToken && now < cred.tokenExpiry) return cred.accessToken;
try {
const res = await fetch(OPENSKY_TOKEN_URL, {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "client_credentials",
client_id: cred.clientId,
client_secret: cred.clientSecret,
}),
});
if (!res.ok) return null;
const data = await res.json();
cred.accessToken = data.access_token;
cred.tokenExpiry = now + data.expires_in * 1000 - 30_000;
return cred.accessToken;
} catch {
return null;
}
}
// ─── Poller ──────────────────────────────────────────────────
const insertHistory = db.prepare(`
INSERT OR IGNORE INTO aviation_history (icao24, ts, lat, lon, alt, hdg, spd, fetched_at)
VALUES (@icao24, @ts, @lat, @lon, @alt, @hdg, @spd, @fetched_at)
`);
async function pollOpenSky() {
const pollStart = Date.now();
console.log(`[Aviation] Poll starting...`);
const cred = getActiveCredential();
let token = null;
if (cred) {
token = await fetchTokenForCredential(cred);
}
const headers: Record<string, string> = {};
if (token) {
headers["Authorization"] = `Bearer ${token}`;
}
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 12000);
const response = await fetch(OPENSKY_DATA_URL, { headers, signal: controller.signal });
clearTimeout(timeoutId);
// Handle limits
if (response.status === 429) {
console.warn('[Aviation] 429 Rate Limit hit.');
if (cred) rotateCredential();
return;
}
const creditsRemainingStr = response.headers.get("x-ratelimit-remaining");
if (creditsRemainingStr && cred) {
const rem = parseInt(creditsRemainingStr, 10);
cred.creditsRemaining = rem;
if (rem <= ROTATION_THRESHOLD) rotateCredential();
}
if (!response.ok) throw new Error(`Status ${response.status}`);
const data = await response.json();
if (data.states && Array.isArray(data.states)) {
const activeStates = data.states.filter((s: any) => s[6] !== null && s[5] !== null);
messageBuffer.push(activeStates);
console.log(`[Aviation] Poll OK: ${activeStates.length} aircraft in ${Date.now() - pollStart}ms`);
}
} catch (err: any) {
console.error(`[Aviation] Polling Error (${Date.now() - pollStart}ms): ${err.message}`);
}
}
async function flushBuffer() {
if (messageBuffer.length === 0) return;
// We only take the most recent state array from the buffer queue completely resetting it
const latestStates = messageBuffer.pop();
messageBuffer = [];
if (!latestStates || latestStates.length === 0) return;
const fetchedAt = Math.floor(Date.now() / 1000);
const fleetObj: Record<string, any> = Object.create(null);
let insertedCount = 0;
const insertMany = db.transaction((states) => {
for (const s of states) {
const icao24 = s[0] as string;
const callsign = (s[1] as string)?.trim() || null;
const ts = s[3] as number || s[4] as number || fetchedAt; // time_position or last_contact
const lon = s[5] as number;
const lat = s[6] as number;
const alt = s[7] as number; // baro_altitude
const on_ground = s[8] as boolean;
const spd = s[9] as number;
const hdg = s[10] as number;
// 1. Write History to SQLite
if (!on_ground) {
const result = insertHistory.run({
icao24, ts, lat, lon, alt, hdg, spd, fetched_at: fetchedAt
});
if (result.changes > 0) insertedCount++;
}
// 2. Prepare Live Cache structure
// Zero out speed for grounded aircraft so frontend stops extrapolating
const stateObj = {
icao24,
callsign,
origin_country: s[2],
time_position: s[3],
last_contact: s[4],
lon,
lat,
alt,
on_ground,
spd: on_ground ? 0 : spd,
hdg: on_ground ? 0 : hdg,
vertical_rate: s[11],
sensors: s[12],
geo_altitude: s[13],
squawk: s[14],
spi: s[15],
position_source: s[16],
last_updated: fetchedAt
};
fleetObj[icao24] = stateObj;
}
});
try {
insertMany(latestStates);
// Execute Redis batch via compressed snapshot (10 mins)
await setLiveSnapshot('aviation', fleetObj, 10 * 60);
} catch (err) {
console.error('[Aviation] Buffer flush failed:', err);
}
}
export function startAviationPoller() {
initCredentialPool();
console.log('[Aviation] Starting background polling...');
// Daily reset at midnight
cron.schedule('0 0 * * *', () => {
resetCredentialPool();
});
setInterval(pollOpenSky, POLLING_INTERVAL_MS);
setInterval(flushBuffer, FLUSH_INTERVAL_MS);
// Initial fetch
pollOpenSky();
}
registerSeeder({
name: "aviation",
init: startAviationPoller
});
@@ -0,0 +1,146 @@
import { db } from '../db';
import { setLiveSnapshot } from '../redis';
import { fetchWithTimeout, withRetry } from '../seed-utils';
import { registerSeeder } from '../scheduler';
import { randomUUID } from 'crypto';
interface GdeltFeature {
type: string;
geometry: { type: string, coordinates: number[] };
properties: {
urlpubtimedate: string;
name: string;
domain: string;
url: string;
urltone: number;
};
}
const GDELT_URL = 'http://api.gdeltproject.org/api/v1/gkg_geojson?query=protest OR riot OR demonstration OR strike OR clash&maxrows=2500';
function classifyGdeltEventType(name: string) {
const lowerName = name.toLowerCase();
if (lowerName.includes('riot')) return 'Riots';
if (lowerName.includes('clash')) return 'Riots';
if (lowerName.includes('strike')) return 'Strikes';
if (lowerName.includes('demonstration')) return 'Demonstrations';
return 'Protests';
}
function classifyGdeltSubType(name: string, count: number) {
const lowerName = name.toLowerCase();
if (count > 50 || lowerName.includes('riot') || lowerName.includes('clash')) return 'Violent demonstration';
if (lowerName.includes('strike')) return 'Labor strike';
return 'Peaceful protest';
}
const insertUnrest = db.prepare(
'INSERT OR REPLACE INTO civil_unrest (id, payload, source_ts, fetched_at) VALUES (@id, @payload, @source_ts, @fetched_at)'
);
export async function seedCivilUnrest() {
console.log('[CivilUnrest] Fetching from GDELT API...');
const res = await withRetry(() => fetchWithTimeout(GDELT_URL, { headers: { 'User-Agent': 'WWV-Data-Engine' } }, 25000), 3, 5000);
if (!res.ok) {
console.warn(`[CivilUnrest] Failed to fetch. HTTP ${res.status}`);
return;
}
const json = await res.json();
const features = json.features as GdeltFeature[];
if (!features || features.length === 0) {
console.log('[CivilUnrest] No events returned from GDELT.');
return;
}
// Aggregate by location
const locationMap = new Map<string, any>();
for (const feature of features) {
const name = feature.properties?.name || '';
if (!name) continue;
const coords = feature.geometry?.coordinates;
if (!Array.isArray(coords) || coords.length < 2) continue;
const [lon, lat] = coords;
if (!Number.isFinite(lat) || !Number.isFinite(lon) || lat < -90 || lat > 90 || lon < -180 || lon > 180) continue;
// Grid snap to ~11km clustering
const key = `${lat.toFixed(1)}:${lon.toFixed(1)}`;
const existing = locationMap.get(key);
if (existing) {
existing.count++;
existing.urls.push(feature.properties.url);
if (feature.properties.urltone < existing.worstTone) {
existing.worstTone = feature.properties.urltone;
}
} else {
locationMap.set(key, {
name,
lat,
lon,
count: 1,
worstTone: feature.properties.urltone ?? 0,
date: feature.properties.urlpubtimedate,
urls: [feature.properties.url]
});
}
}
const fetchedAt = Date.now();
const items: any[] = [];
for (const [, loc] of locationMap) {
if (loc.count < 3) continue; // Filter noise
const country = loc.name.split(',').pop()?.trim() || "Unknown";
const eventType = classifyGdeltEventType(loc.name);
// Create aggregated cluster event
const item = {
id: `gdelt-${loc.lat.toFixed(2)}-${loc.lon.toFixed(2)}`,
lat: loc.lat,
lon: loc.lon,
type: eventType,
subType: classifyGdeltSubType(loc.name, loc.count),
actor1: "General Public",
actor2: "N/A",
fatalities: 0,
country,
location: loc.name,
date: loc.date,
source: "GDELT",
notes: `${loc.count} clustered reports. Worst Tone: ${loc.worstTone.toFixed(1)}`,
reportCount: loc.count
};
items.push(item);
insertUnrest.run({
id: item.id,
payload: JSON.stringify(item),
source_ts: new Date(item.date).getTime(),
fetched_at: fetchedAt
});
}
console.log(`[CivilUnrest] Clustered ${features.length} mentions into ${items.length} confirmed unrest events.`);
await setLiveSnapshot(
'civil_unrest',
{
source: 'gdelt',
fetchedAt: new Date().toISOString(),
items,
totalCount: items.length
},
86400
);
}
registerSeeder({
name: 'civilUnrest',
cron: '*/15 * * * *',
fn: seedCivilUnrest
});
@@ -0,0 +1,140 @@
import { db } from '../db';
import { setLiveSnapshot } from '../redis';
import { registerSeeder } from '../scheduler';
import crypto from 'crypto';
interface ConflictEvent {
id: string;
latitude: number;
longitude: number;
type: string;
subType: string;
actor1: string;
actor2: string;
fatalities: number;
date: string;
source: string;
notes: string;
}
const CONFLICT_HOTSPOTS = [
{ lat: 48.3794, lon: 31.1656, radius: 5 }, // Ukraine
{ lat: 31.0461, lon: 34.8516, radius: 2 }, // Israel/Gaza
{ lat: 15.5007, lon: 32.5599, radius: 6 }, // Sudan
{ lat: 15.3694, lon: 44.1910, radius: 3 }, // Yemen
{ lat: 14.4974, lon: 14.4524, radius: 8 }, // Sahel region
{ lat: 16.8661, lon: 96.1951, radius: 5 }, // Myanmar
{ lat: 5.1521, lon: 46.1996, radius: 4 }, // Somalia
];
const EVENT_TYPES = [
'Battles',
'Explosions/Remote violence',
'Violence against civilians',
'Protests',
'Riots',
'Strategic developments'
];
const WEAPON_TYPES = [
'Artillery',
'Airstrike',
'Drone strike',
'Armed clashes',
'IED',
'Small arms'
];
function generateMockConflictEvents(): ConflictEvent[] {
const events: ConflictEvent[] = [];
const today = new Date().toISOString().split('T')[0];
for (const hotspot of CONFLICT_HOTSPOTS) {
const numEvents = Math.floor(Math.random() * 10) + 5; // 5-15 events per hotspot
for (let i = 0; i < numEvents; i++) {
const u = Math.random();
const v = Math.random();
const w = hotspot.radius / 111.0;
const t = 2 * Math.PI * v;
const x = w * Math.cos(t);
const y = w * Math.sin(t);
const lat = hotspot.lat + y;
const lon = hotspot.lon + x;
const type = EVENT_TYPES[Math.floor(Math.random() * EVENT_TYPES.length)];
const subType = WEAPON_TYPES[Math.floor(Math.random() * WEAPON_TYPES.length)];
const fatalities = Math.floor(Math.random() * 10) === 0 ? Math.floor(Math.random() * 50) : Math.floor(Math.random() * 5); // mostly small, some mass
events.push({
id: crypto.randomUUID(),
latitude: lat,
longitude: lon,
type,
subType,
actor1: 'Unidentified Armed Group',
actor2: 'State Forces',
fatalities,
date: today,
source: 'Mock ACLED Data',
notes: 'Reported ' + type.toLowerCase() + ' involving ' + subType.toLowerCase() + '.'
});
}
}
return events;
}
const insertStmt = db.prepare('INSERT OR REPLACE INTO conflict_events (id, payload, source_ts, fetched_at) VALUES (@id, @payload, @source_ts, @fetched_at)');
export async function fetchConflictEvents() {
console.log('[Seeder: ConflictEvents] Mocking ACLED data generation...');
const events = generateMockConflictEvents();
const now = Date.now();
let inserted = 0;
const insertMany = db.transaction((rows: any[]) => {
for (const row of rows) {
insertStmt.run(row);
inserted++;
}
});
const dbRows = events.map(e => ({
id: e.id,
payload: JSON.stringify(e),
source_ts: now,
fetched_at: now
}));
insertMany(dbRows);
console.log('[Seeder: ConflictEvents] Inserted ' + inserted + ' events into DB.');
try {
const geoEntities = events.map(e => ({
id: 'conflict-' + e.id,
latitude: e.latitude,
longitude: e.longitude,
properties: {
type: e.type,
subType: e.subType,
fatalities: e.fatalities,
actor1: e.actor1,
actor2: e.actor2,
date: e.date,
notes: e.notes
}
}));
await setLiveSnapshot('conflict_events', geoEntities, 3600 * 24); // Cache for 24 hours
} catch (err) {
console.warn('[Seeder: ConflictEvents] Redis cache failed:', err);
}
}
registerSeeder({
name: 'conflictEvents',
cron: '0 0 * * *', // Run daily at midnight
fn: fetchConflictEvents
});
@@ -0,0 +1,156 @@
import { db } from '../db';
import { setLiveSnapshot } from '../redis';
import { fetchWithTimeout, withRetry } from '../seed-utils';
import { registerSeeder } from '../scheduler';
import { geolocateIp } from '../geoip';
const OTX_BASE = 'https://otx.alienvault.com/api/v1';
const insertCyberAttack = db.prepare(
'INSERT OR REPLACE INTO cyber_attacks (id, payload, source_ts, fetched_at) VALUES (@id, @payload, @source_ts, @fetched_at)'
);
interface OtxIndicator {
id: number;
indicator: string;
type: string;
title: string;
description: string;
}
interface OtxPulse {
id: string;
name: string;
description: string;
created: string;
modified: string;
adversary: string;
targeted_countries: string[];
attack_ids: { id: string; name: string }[];
malware_families: string[];
indicators: OtxIndicator[];
tags: string[];
}
export async function seedCyberAttacks() {
const apiKey = process.env.OTX_API_KEY;
if (!apiKey) {
console.warn('[CyberAttacks] OTX_API_KEY not set — skipping.');
return;
}
console.log('[CyberAttacks] Polling AlienVault OTX...');
// Fetch pulses modified in the last 48 hours
const since = new Date(Date.now() - 48 * 3600 * 1000).toISOString();
const url = `${OTX_BASE}/pulses/subscribed?modified_since=${since}&limit=50`;
const res = await withRetry(async () => {
try {
return await fetchWithTimeout(url, {
headers: { 'X-OTX-API-KEY': apiKey, 'User-Agent': 'WWV-Data-Engine' },
});
} catch(err) {
const msg = err instanceof Error ? err.message : String(err);
console.error('[CyberAttacks] Fetch error details:', msg);
throw err;
}
});
const data = await res.json();
if (!data?.results || !Array.isArray(data.results)) {
console.warn('[CyberAttacks] Invalid OTX response');
return;
}
const pulses: OtxPulse[] = data.results;
const fetchedAt = Date.now();
const items: any[] = [];
const seenIps = new Set<string>();
for (const pulse of pulses) {
// Extract only IPv4 indicators
const ipIndicators = (pulse.indicators || []).filter(
(ind) => ind.type === 'IPv4'
);
for (const ind of ipIndicators) {
if (seenIps.has(ind.indicator)) continue;
seenIps.add(ind.indicator);
const geo = geolocateIp(ind.indicator);
if (!geo) continue; // Skip un-geolocatable IPs
const threatType = classifyThreat(pulse);
const item = {
id: `otx-${pulse.id}-${ind.id}`,
ip: ind.indicator,
lat: geo.lat,
lon: geo.lon,
country: geo.country,
city: geo.city,
threatType,
adversary: pulse.adversary || 'Unknown',
pulseName: pulse.name,
pulseDescription: pulse.description?.slice(0, 300) || '',
malwareFamilies: pulse.malware_families || [],
tags: pulse.tags?.slice(0, 5) || [],
targetedCountries: pulse.targeted_countries || [],
pulseId: pulse.id,
pulseCreated: pulse.created,
pulseModified: pulse.modified,
};
items.push(item);
// Persist to SQLite
insertCyberAttack.run({
id: item.id,
payload: JSON.stringify(item),
source_ts: new Date(pulse.modified).getTime(),
fetched_at: fetchedAt,
});
}
}
console.log(
`[CyberAttacks] Processed ${pulses.length} pulses → ${items.length} geolocated indicators.`
);
// Save to Redis
await setLiveSnapshot(
'cyber_attacks',
{
source: 'cyber_attacks',
fetchedAt: new Date().toISOString(),
items,
totalCount: items.length,
},
7200 // 2 hour TTL
);
}
function classifyThreat(pulse: OtxPulse): string {
const tags = (pulse.tags || []).map((t) => t.toLowerCase());
const name = pulse.name.toLowerCase();
const desc = (pulse.description || '').toLowerCase();
const combined = [...tags, name, desc].join(' ');
if (combined.includes('apt') || combined.includes('advanced persistent'))
return 'APT';
if (combined.includes('ransomware')) return 'Ransomware';
if (combined.includes('botnet')) return 'Botnet';
if (combined.includes('phishing')) return 'Phishing';
if (combined.includes('ddos')) return 'DDoS';
if (combined.includes('malware') || combined.includes('trojan'))
return 'Malware';
if (combined.includes('c2') || combined.includes('command and control'))
return 'C2 Server';
return 'Other';
}
registerSeeder({
name: 'cyber_attacks',
cron: '0 */2 * * *', // Every 2 hours
fn: seedCyberAttacks,
});
@@ -0,0 +1,99 @@
import { db } from '../db';
import { setLiveSnapshot } from '../redis';
import { fetchWithTimeout, withRetry, haversineKm } from '../seed-utils';
import { registerSeeder } from '../scheduler';
const KNOWN_TEST_SITES = [
{ name: 'Punggye-ri (North Korea)', lat: 41.278, lon: 129.088 },
{ name: 'Lop Nur (China)', lat: 40.75, lon: 89.6 },
{ name: 'Nevada Test Site (USA)', lat: 37.13, lon: -116.04 },
{ name: 'Semipalatinsk (Kazakhstan)', lat: 50.4, lon: 77.8 },
{ name: 'Novaya Zemlya (Russia)', lat: 73.3, lon: 54.9 },
{ name: 'Pokhran (India)', lat: 27.09, lon: 71.75 },
{ name: 'Chagai (Pakistan)', lat: 28.79, lon: 64.91 },
{ name: 'Moruroa (France)', lat: -21.83, lon: -138.88 },
];
const insertEarthquake = db.prepare('INSERT OR IGNORE INTO earthquakes (id, payload, source_ts, fetched_at) VALUES (@id, @payload, @source_ts, @fetched_at)');
export async function seedEarthquakes() {
console.log('[Earthquakes] Polling USGS...');
// USGS GeoJSON Feed: 4.5+ magnitude, past 7 days
const url = 'https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/4.5_week.geojson';
const res = await withRetry(() => fetchWithTimeout(url));
const data = await res.json();
const fetchedAt = Date.now();
if (!data?.features || !Array.isArray(data.features)) {
console.warn('[Earthquakes] Invalid response from USGS');
return;
}
const items = [];
let insertedCount = 0;
for (const feature of data.features) {
const { id, properties, geometry } = feature;
const [lon, lat, depth] = geometry.coordinates;
const sourceTs = properties.time;
// Detect nuclear test site proximity (< 10km)
let nearTestSite = false;
let nearestSiteName = null;
let minDistance = Infinity;
for (const site of KNOWN_TEST_SITES) {
const dist = haversineKm(lat, lon, site.lat, site.lon);
if (dist < minDistance) {
minDistance = dist;
if (dist < 10) { // Within 10km is highly suspicious
nearTestSite = true;
nearestSiteName = site.name;
}
}
}
const item = {
id,
place: properties.place,
magnitude: properties.mag,
depth_km: depth,
lat,
lon,
occurredAt: sourceTs,
url: properties.url,
nearTestSite,
nearestSiteName,
distanceToTestSiteKm: minDistance < 50 ? minDistance : undefined
};
items.push(item);
// Save to SQLite
const result = insertEarthquake.run({
id,
payload: JSON.stringify(item),
source_ts: sourceTs,
fetched_at: fetchedAt
});
if (result.changes > 0) insertedCount++;
}
console.log(`[Earthquakes] Parsed ${items.length} earthquakes. Saved ${insertedCount} new to SQLite.`);
// Save to Redis Live Cache
await setLiveSnapshot('earthquakes', {
source: "earthquakes",
fetchedAt: new Date().toISOString(),
items: items,
totalCount: items.length
}, 3600); // 1 hour TTL
}
registerSeeder({
name: "earthquakes",
cron: "0 * * * *", // Every hour
fn: seedEarthquakes
});
@@ -0,0 +1,95 @@
import { db } from '../db';
import { setLiveSnapshot } from '../redis';
import { registerSeeder } from '../scheduler';
import { randomUUID } from 'crypto';
const insertGpsJam = db.prepare('INSERT OR REPLACE INTO gps_jamming (id, payload, source_ts, fetched_at) VALUES (@id, @payload, @source_ts, @fetched_at)');
const HOTSPOTS = [
{ name: 'Eastern Europe / Ukraine', lat: 48.0, lon: 37.0, radiusDeg: 5, intensity: 'high' },
{ name: 'Baltic Sea Region', lat: 58.0, lon: 20.0, radiusDeg: 4, intensity: 'high' },
{ name: 'Middle East', lat: 33.0, lon: 36.0, radiusDeg: 6, intensity: 'high' },
{ name: 'Black Sea', lat: 43.0, lon: 34.0, radiusDeg: 3, intensity: 'medium' },
{ name: 'Korean Peninsula', lat: 38.0, lon: 127.0, radiusDeg: 2, intensity: 'medium' },
];
function generateMockData() {
const items = [];
const now = Date.now();
for (const hotspot of HOTSPOTS) {
// Generate 50-150 points per hotspot
const count = Math.floor(Math.random() * 100) + 50;
for (let i = 0; i < count; i++) {
// Random offset within radius using somewhat normal distribution
const u = Math.random() + Math.random() - 1;
const v = Math.random() + Math.random() - 1;
const lat = hotspot.lat + (u * hotspot.radiusDeg);
const lon = hotspot.lon + (v * hotspot.radiusDeg);
// Intensity decreases slightly away from center
const distFromCenter = Math.sqrt(u*u + v*v);
let pointIntensity = hotspot.intensity;
if (hotspot.intensity === 'high' && distFromCenter > 0.6) {
pointIntensity = 'medium';
}
if (pointIntensity === 'medium' && distFromCenter > 0.8) {
pointIntensity = 'low';
}
items.push({
id: randomUUID(),
lat,
lon,
interferenceLevel: pointIntensity,
timestamp: now,
region: hotspot.name
});
}
}
return items;
}
export async function seedGpsJam() {
console.log('[GPS Jamming] Generating daily interference map snapshot...');
const fetchedAt = Date.now();
const sourceTs = fetchedAt; // Represents end of the 24h period for the map
const items = generateMockData();
let insertedCount = 0;
db.transaction(() => {
// Optional: clear old data to keep DB size small if this is just a daily map
db.exec('DELETE FROM gps_jamming');
for (const item of items) {
const result = insertGpsJam.run({
id: item.id,
payload: JSON.stringify(item),
source_ts: sourceTs,
fetched_at: fetchedAt
});
if (result.changes > 0) insertedCount++;
}
})();
console.log(`[GPS Jamming] Generated ${items.length} points. Saved ${insertedCount} to SQLite.`);
// Save to Redis Live Cache
await setLiveSnapshot('gps_jamming', {
source: "gpsjam_mock",
fetchedAt: new Date().toISOString(),
items: items,
totalCount: items.length
}, 86400); // 24 hours TTL
}
registerSeeder({
name: "gps_jamming",
cron: "0 0 * * *", // Once daily at midnight
fn: seedGpsJam
});
@@ -0,0 +1,14 @@
import './iranwarlive';
import './earthquakes';
import './wildfires';
import './maritime';
import './aviation';
import './military-aviation';
import './satellite';
// --- TEMPORARILY DISABLED FOR DEMO (MOCK DATA) ---
import './gpsjam';
// import './conflictEvents';
import './civilUnrest';
import './cyberAttacks';
import './sanctions';
@@ -0,0 +1,153 @@
import fs from 'fs';
import path from 'path';
import { z } from 'zod';
import { db } from '../db';
import { setLiveSnapshot } from '../redis';
import { fetchWithTimeout, withRetry } from '../seed-utils';
import { registerSeeder } from '../scheduler';
// Zod Schema for input validation to strip unrecognized injection keys
const itemSchema = z.object({
event_id: z.string().max(255),
type: z.string().max(255).nullable().optional(),
location: z.string().max(500).nullable().optional(),
timestamp: z.string().max(100),
confidence: z.string().max(100).nullable().optional(),
event_summary: z.string().max(10000).nullable().optional(),
source_url: z.string().max(2000).nullable().optional(),
preview_image: z.string().url().max(2000).nullable().optional(),
_osint_meta: z.any().optional()
});
const insertEvent = db.prepare(`
INSERT INTO iranwar_events (event_id, payload, timestamp, fetched_at)
VALUES (@event_id, @payload, @timestamp, @fetched_at)
ON CONFLICT(event_id) DO UPDATE SET
payload=excluded.payload,
timestamp=excluded.timestamp
`);
const getTopEvents = db.prepare('SELECT payload FROM iranwar_events ORDER BY timestamp DESC LIMIT 500');
let hasHydratedSeed = false;
export async function seedIranWarLive() {
// --- SELF-HEALING HISTORY SEED ---
if (!hasHydratedSeed) {
console.log('[IranWarLive] Initializing: Hydrating/Upserting active fallback seed...');
const seedPath = path.join(__dirname, '..', '..', 'seedData', 'iranwar_seed.json');
if (fs.existsSync(seedPath)) {
const fallbackData = JSON.parse(fs.readFileSync(seedPath, 'utf8'));
const fetchedAt = Date.now();
let insertedCount = 0;
let variables = 0;
const upsertMany = db.transaction((events: any[]) => {
for (const item of events) {
try {
const validatedItem = itemSchema.parse(item);
const result = insertEvent.run({
event_id: validatedItem.event_id,
payload: JSON.stringify(validatedItem),
timestamp: validatedItem.timestamp,
fetched_at: fetchedAt
});
if (result.changes > 0) insertedCount++;
} catch(err) { /* ignore validation errors in fallback */ }
}
});
upsertMany(fallbackData);
console.log(`[IranWarLive] Boot hydration complete. Merged ${insertedCount} seed events.`);
}
hasHydratedSeed = true;
}
console.log('[IranWarLive] Polling iranwarlive.com/feed.json...');
let data: any = null;
try {
const response = await withRetry(() => fetchWithTimeout('https://iranwarlive.com/feed.json', {
headers: {
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
"Accept": "application/json, text/plain, */*",
"Cache-Control": "no-cache",
"Accept-Language": "en-US,en;q=0.9"
}
}));
if(!response.ok) throw new Error(`HTTP ${response.status}`);
data = await response.json();
} catch(err: any) {
console.warn(`[IranWarLive] Failed to fetch live feed (anti-bot block?): ${err.message}. Using local database cache.`);
}
if (data && data.items && Array.isArray(data.items) && data.items.length > 0) {
const fetchedAt = Date.now();
let insertedCount = 0;
// Find completely new items to hydrate
const placeholders = data.items.map(() => '?').join(',');
const existingIdsStmt = db.prepare(`SELECT event_id FROM iranwar_events WHERE event_id IN (${placeholders})`);
const existingIdsRow = existingIdsStmt.all(...data.items.map((i: any) => i.event_id)) as { event_id: string }[];
const existingIds = new Set(existingIdsRow.map(row => row.event_id));
const newItems = data.items.filter((item: any) => !existingIds.has(item.event_id));
if (newItems.length > 0) {
console.log(`[IranWarLive] Found ${newItems.length} new events. Hydrating og:images...`);
for (const item of newItems) {
if (item.source_url) {
try {
const htmlRes = await fetchWithTimeout(item.source_url, { headers: { "User-Agent": "WorldWideView-OSINT/1.0" } }, 5000);
const html = await htmlRes.text();
const ogMatch = html.match(/<meta[^>]*property=["']og:image["'][^>]*content=["']([^"']+)["']/i)
|| html.match(/<meta[^>]*content=["']([^"']+)["'][^>]*property=["']og:image["']/i);
if (ogMatch && ogMatch[1]) {
item.preview_image = ogMatch[1];
}
} catch (err: any) {
console.warn(`[IranWarLive] Failed to hydrate image for ${item.event_id}: ${err.message}`);
}
}
}
const insertMany = db.transaction((events: any[]) => {
for (const item of events) {
try {
const validatedItem = itemSchema.parse(item);
const result = insertEvent.run({
event_id: validatedItem.event_id,
payload: JSON.stringify(validatedItem),
timestamp: validatedItem.timestamp,
fetched_at: fetchedAt
});
if (result.changes > 0) insertedCount++;
} catch(err: any) {
console.warn(`[IranWarLive] Skipped item due to validation error: ${err.message}`);
}
}
});
insertMany(newItems);
if (insertedCount > 0) {
console.log(`[IranWarLive] Added ${insertedCount} new hydrated events to history.`);
}
} else {
console.log('[IranWarLive] No new events found.');
}
}
// ALways update Redis hot cache with the latest 500 events
const rows = getTopEvents.all() as { payload: string }[];
const history = rows.map(row => JSON.parse(row.payload));
await setLiveSnapshot('iranwarlive', {
source: "iranwarlive",
fetchedAt: new Date().toISOString(),
items: history
}, 3600); // 1 hour TTL in Redis
}
// Register with scheduler
registerSeeder({
name: "iranwarlive",
cron: "*/1 * * * *", // Every minute
fn: seedIranWarLive
});
@@ -0,0 +1,147 @@
import WebSocket from 'ws';
import { db } from '../db';
import { redis, setLiveSnapshot } from '../redis';
import { registerSeeder } from '../scheduler';
const AISSTREAM_URL = 'wss://stream.aisstream.io/v0/stream';
const API_KEY = process.env.AISSTREAM_API_KEY;
// Buffer to batch SQLite inserts
let messageBuffer: any[] = [];
const activeFleetCache = new Map<string, any>();
const FLUSH_INTERVAL_MS = 15000;
let isFlushIntervalRunning = false;
// SQLite insert statement
const insertHistory = db.prepare(`
INSERT OR IGNORE INTO maritime_history (mmsi, ts, lat, lon, hdg, spd, fetched_at)
VALUES (@mmsi, @ts, @lat, @lon, @hdg, @spd, @fetched_at)
`);
async function flushBuffer() {
if (messageBuffer.length === 0) return;
const batch = [...messageBuffer];
messageBuffer = [];
const fetchedAt = Date.now();
let insertedCount = 0;
// 1. Bulk insert to SQLite for permanent history
const insertMany = db.transaction((msgs) => {
for (const msg of msgs) {
if (!msg.MetaData?.MMSI || !msg.Message?.PositionReport) continue;
const mmsi = msg.MetaData.MMSI.toString();
const report = msg.Message.PositionReport;
const ts = Math.floor(new Date(msg.MetaData.time_utc).getTime() / 1000); // Epoch seconds
const result = insertHistory.run({
mmsi,
ts,
lat: report.Latitude,
lon: report.Longitude,
hdg: report.TrueHeading,
spd: report.Sog,
fetched_at: fetchedAt
});
if (result.changes > 0) insertedCount++;
}
});
try {
insertMany(batch);
if (insertedCount > 0) {
// console.log(`[Maritime] Flushed ${insertedCount} new positions to SQLite history`);
}
// 2. Update memory cache and serialize to snapshot
const nowSecs = Math.floor(Date.now() / 1000);
// Cleanup stale ships (>6 hours)
for (const [mmsi, ship] of activeFleetCache.entries()) {
if (nowSecs - ship.last_updated > 6 * 3600) {
activeFleetCache.delete(mmsi);
}
}
for (const msg of batch) {
if (!msg.MetaData?.MMSI || !msg.Message?.PositionReport) continue;
const mmsi = msg.MetaData.MMSI.toString();
const report = msg.Message.PositionReport;
const ts = Math.floor(new Date(msg.MetaData.time_utc).getTime() / 1000);
const shipState = {
id: `mmsi-${mmsi}`,
mmsi,
name: msg.MetaData.ShipName ? msg.MetaData.ShipName.trim() : `Unknown (${mmsi})`,
lat: report.Latitude,
lon: report.Longitude,
hdg: report.TrueHeading,
spd: report.Sog,
last_updated: ts
};
activeFleetCache.set(mmsi, shipState);
}
await setLiveSnapshot('maritime', Object.fromEntries(activeFleetCache), 6 * 3600);
} catch (err) {
console.error('[Maritime] Buffer flush failed:', err);
}
}
export function startMaritimeWebsocket() {
if (!API_KEY) {
console.warn('[Maritime] Skipping AIS websocket: AISSTREAM_API_KEY not set.');
return;
}
console.log('[Maritime] Connecting to AisStream.io...');
const ws = new WebSocket(AISSTREAM_URL);
ws.on('open', () => {
console.log('[Maritime] WebSocket connected. Subscribing to global feed...');
// Bounding box for English Channel / Strait of Hormuz / global (up to API tier)
// Here we request global or specific high-traffic boxes
const subscriptionMessage = {
APIKey: API_KEY,
BoundingBoxes: [[[-90, -180], [90, 180]]], // Global (requires paid tier for real use)
FiltersShipMMSI: [], // All ships
FilterMessageTypes: ["PositionReport"]
};
ws.send(JSON.stringify(subscriptionMessage));
});
ws.on('message', (data) => {
try {
const msg = JSON.parse(data.toString());
if (msg.MessageType === "PositionReport" || msg.Message?.PositionReport) {
messageBuffer.push(msg);
}
} catch (e) {
// ignore parse errors
}
});
ws.on('error', (err) => {
console.error('[Maritime] WebSocket error:', err.message);
});
ws.on('close', () => {
console.log('[Maritime] WebSocket closed. Reconnecting in 5s...');
setTimeout(startMaritimeWebsocket, 5000);
});
// Start background flush loop safely
if (!isFlushIntervalRunning) {
setInterval(flushBuffer, FLUSH_INTERVAL_MS);
isFlushIntervalRunning = true;
}
}
// Register initialization logic. No cron needed, runs infinitely.
registerSeeder({
name: "maritime",
init: startMaritimeWebsocket
});
@@ -0,0 +1,101 @@
import { db } from '../db';
import { setLiveSnapshot } from '../redis';
import { registerSeeder } from '../scheduler';
const ADSB_LOL_URL = "https://api.adsb.lol/v2/mil";
const POLLING_INTERVAL_MS = 60000;
const insertHistory = db.prepare(`
INSERT OR IGNORE INTO military_aviation_history (hex, ts, lat, lon, alt, hdg, spd, fetched_at)
VALUES (@hex, @ts, @lat, @lon, @alt, @hdg, @spd, @fetched_at)
`);
async function pollMilitaryAviation() {
try {
const response = await fetch(ADSB_LOL_URL, {
headers: {
"User-Agent": "WorldWideView-DataEngine"
}
});
if (!response.ok) {
if (response.status === 429) {
console.warn('[MilitaryAviation] 429 Rate Limit hit.');
}
throw new Error(`Status ${response.status}`);
}
const data = await response.json();
if (!data.ac || !Array.isArray(data.ac)) return;
const fetchedAt = Math.floor(Date.now() / 1000);
const fleetObj: Record<string, any> = Object.create(null);
let insertedCount = 0;
const insertMany = db.transaction((aircraft) => {
for (const ac of aircraft) {
if (ac.lat == null || ac.lon == null) continue;
const hex = ac.hex;
// Some fields might be missing depending on coverage
const ts = Math.floor((ac.seen_pos != null ? (Date.now() - ac.seen_pos * 1000) : Date.now()) / 1000); // Approximate timestamp based on seen_pos
const lon = ac.lon;
const lat = ac.lat;
const alt = typeof ac.alt_baro === "number" ? ac.alt_baro : 0;
const on_ground = ac.alt_baro === "ground";
const spd = ac.gs || 0;
const hdg = ac.track || 0;
// 1. Write History to SQLite
if (!on_ground) {
const result = insertHistory.run({
hex, ts, lat, lon, alt, hdg, spd, fetched_at: fetchedAt
});
if (result.changes > 0) insertedCount++;
}
// 2. Prepare Live Cache structure
fleetObj[hex] = {
hex,
flight: ac.flight || null,
r: ac.r || null,
t: ac.t || null,
lat,
lon,
alt_baro: ac.alt_baro,
alt_geom: ac.alt_geom,
gs: ac.gs,
track: ac.track,
squawk: ac.squawk,
dbFlags: ac.dbFlags,
category: ac.category,
emergency: ac.emergency,
seen: ac.seen,
seen_pos: ac.seen_pos,
last_updated: fetchedAt
};
}
});
insertMany(data.ac);
// Execute Redis batch via compressed snapshot (60 mins to match slow moving or intermittent adsb.lol coverage)
await setLiveSnapshot('military-aviation', fleetObj, 60 * 60);
} catch (err: any) {
console.error(`[MilitaryAviation] Polling Error: ${err.message}`);
}
}
export function startMilitaryAviationPoller() {
console.log('[MilitaryAviation] Starting background polling...');
setInterval(pollMilitaryAviation, POLLING_INTERVAL_MS);
// Initial fetch
pollMilitaryAviation();
}
registerSeeder({
name: "military-aviation",
init: startMilitaryAviationPoller
});
Loaded 100 of 360 files, more files were not shown because too many files have changed in this diff. Show more