Adds an opt-in agent integration surface that lets a trusted external
tool (running as the same logged-in user) drive the running WWV browser
session — fly the globe, toggle layers, focus entities — by POSTing
JSON actions to the server, which fans them out over SSE to every
connected browser tab belonging to that user.
The motivating use case is an MCP server (a Model Context Protocol
adapter): an LLM agent calls a tool like `globe_fly_to({lat, lon})`,
the MCP server posts to `/api/agent/publish`, the browser subscriber
re-emits the action onto the existing client-side `dataBus`, and the
React + Cesium app handles it the same way it would handle any UI
button click. Read-only camera / engine queries already work via the
existing REST surface — this PR adds the missing write path.
What's added:
- `src/lib/agent/bus.ts` — process-local AgentBus singleton, scoped
per user. Subscriptions live in a `Map<userId, Map<connId, sub>>`
so user A's publish never reaches user B's stream, even though
both run on the same Node process.
- `src/app/api/agent/stream/route.ts` — SSE channel. Auth-gated. Sends
initial `:connected` + `retry:3000` directives and a `:hb` heartbeat
every 25s so intermediary proxies (Caddy, Nginx, CDNs) don't tear
down a "stalled" connection.
- `src/app/api/agent/publish/route.ts` — POST endpoint. Accepts JSON
AgentAction shapes (`fly_to`, `face_towards`, `layer_toggle`,
`highlight_layer`, `select_entity`, `ping`), broadcasts only to the
publishing user's bus bucket. Returns `{delivered, subscribers}` so
the caller knows how many tabs received the command.
- `src/components/layout/AgentBusSubscriber.tsx` — browser EventSource
client. Re-emits received actions onto `dataBus` (`cameraGoTo`,
`cameraFaceTowards`, `layerToggled`, `entitySelected`) — every plugin
is already listening on those channels, so no plugin changes needed.
- `AppShell.tsx` — mounts `AgentBusSubscriber` next to the existing
`DataBusSubscriber`. Two lines.
- `src/app/api/build/route.ts` — `/api/build` returns build id +
timestamp + public flag state. Pairs with a one-line console.log
the subscriber prints on mount so a stale-bundle / config-mismatch
is visible at a glance instead of looking like a feature regression.
Default off via `NEXT_PUBLIC_WWV_AGENT_BUS_ENABLED=true`. An unintended
deployment doesn't open a remote-control channel for users who didn't
opt in.
What's changed in the Dockerfile:
- Adds ARG declarations for the new vars (`NEXT_PUBLIC_WWV_AGENT_BUS_ENABLED`,
`NEXT_PUBLIC_WWV_BUILD_ID`, `NEXT_PUBLIC_WWV_BUILD_AT`).
- Stamps the build with millisecond-precision id + ISO timestamp
(`/app/.build-id`, `/app/.build-at`); both copied into the runner
stage for `/api/build` to read.
- Writes `/app/.env.production.local` from declared ARGs *before*
`next build` runs. Docker doesn't reliably promote ARGs into the
Node child-process environment for the build command, so
`process.env.NEXT_PUBLIC_*` references that previously inlined
through Webpack's DefinePlugin sometimes fell back to runtime
polyfill access (`tV.env.NEXT_PUBLIC_X`) that resolves to `undefined`
in the browser. Writing the env file is the documented Next.js path
and behaves the same on every host.
Default-off, no schema changes, no plugin changes, fully backwards-compatible
on operators who don't opt in.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
WorldWideView
The Open-Source, Plugin-Driven Geospatial Intelligence Engine
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.
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.
Key Features
- "All-Bundle" Plugin Architecture: Ingest any data source dynamically without touching the core platform.
- High-Fidelity 3D Rendering: Google Photorealistic 3D Tiles and LOD modeling powered by CesiumJS.
- Real-Time Data Pipeline: High-frequency WebSocket updates managed by a custom
DataBus. - Advanced Entity Management: Automatic horizon culling, chunked primitive rendering, and 3D stacking/spiderification.
- Marketplace Integration: Download and sync new plugins directly from the UI.
Core Technologies
- 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
DataBusfor high-frequency WebSocket updates - Database: PostgreSQL via Prisma 7
- Deployment: Docker multi-stage build, Coolify
Project Architecture
WorldWideView separates the data acquisition layer from the frontend rendering loop, using a real-time event bus to bridge them.
flowchart TD
subgraph Data Sources
A[Public APIs] -->|Poll| B[Data Engine Seeders]
C[Microservices] -->|Stream| B
end
subgraph Frontend Pipeline
B -->|WebSocket /stream| D[DataBus & WsClient]
D -->|Hydrate| E[Zustand Store]
E -->|Memoized Entities| F[Entity Renderer]
F -->|Primitives| G[CesiumJS Globe]
end
subgraph Plugins
H[Plugin Registry] -->|Load| I[Dynamic Import CDNs]
end
H -.-> D
Prerequisites
Before running the application, ensure you have the following installed:
- Node.js (v18+)
- pnpm (v9+)
- Docker (for self-hosting or full local dev)
- PostgreSQL (or rely on the
coolify-db/ local compose container)
Quick Start (Self-Hosting)
WorldWideView uses a multi-stage Dockerfile designed for standalone output. To deploy instantly on your own server:
Mac/Linux:
mkdir worldwideview && cd worldwideview
curl -fsSL https://raw.githubusercontent.com/silvertakana/worldwideview/main/setup.sh | bash
Windows (PowerShell):
mkdir worldwideview; cd worldwideview
Invoke-WebRequest -Uri https://raw.githubusercontent.com/silvertakana/worldwideview/main/setup.ps1 -UseBasicParsing | Invoke-Expression
Note
Ensure you connect a PostgreSQL database via the
DATABASE_URLenvironment variable for production deployments.
Quick Start (Local Development)
To run the source code locally for contributing or developing:
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
Visit http://localhost:3000 to see the live globe.
Project Structure
The codebase utilizes a pnpm monorepo configuration:
worldwideview/
├── src/ # Core frontend app
│ ├── app/ # Next.js App Router (pages, API routes)
│ ├── components/ # Shared UI, Globe panels, and 3D layouts
│ ├── core/ # DataBus, Polling, PluginManager, Store
│ └── plugins/ # Built-in plugins and registry logic
├── packages/ # Monorepo packages
│ ├── wwv-plugin-sdk/ # SDK interfaces and manifest schemas
│ └── wwv-plugin-*/ # Individual plugins & their backends
├── prisma/ # Database schemas & migrations
└── .agents/ # Agent rules, workflows, and documentation
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.
- Plugin Quickstart Guide: Learn how to scaffold and link your first plugin using the
@worldwideview/cli. - Advanced Plugin Guide: Deep dive into microservice data seeders, WebSockets, complex 3D rendering, and Marketplace publishing.
Repository Ecosystem
WorldWideView is distributed across several specialized repositories:
worldwideview(This Repo): Main frontend, CesiumJS rendering engine, and core plugin framework.wwv-data-engine: Open-source community data backend for polling public APIs.worldwideview-plugins: First-party maintained plugins.worldwideview-marketplace: The web application driving the plugin directory.worldwideview-web: Marketing and landing site.
Development & Workflow
- Branching & Commits: We strictly enforce Conventional Commits (
feat:,fix:,refactor:). Every commit should utilize our semantic versioning[/commit]workflow. - Coding Standards: We emphasize vanilla CSS (no Tailwind), strict TypeScript 5, and file modularity (max 150 lines per file).
- Testing: We use Vitest with
jsdom. All new core logic should be accompanied by tests, running viapnpm test.
See Docs: Development and Docs: Testing for more details.
Contributing
We welcome community contributions! Please review our coding standards and PR processes before submitting code. For detailed instructions on local development and setting up your environment, see our CONTRIBUTING.md.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation Index
Explore our comprehensive documentation suite for detailed engineering insights:
- Project Overview: High-level value proposition and technology stack.
- Architecture: DataBus event stream and Zustand state management.
- Build System: Monorepo structure, Next.js standalone output, and Docker builds.
- Development: Coding conventions and common implementation patterns.
- Testing: Vitest setup and coverage targets.
- Deployment: Coolify integration and persistent volumes.
- Files Catalog: Comprehensive mapping of core source files.
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).
