3.5 KiB
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.
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. WorldWideView is a completely agnostic renderer with absolutely no concept of a "unified" Data Engine; each plugin is a self-contained package that explicitly declares its own streamUrl in its manifest or config.
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 (insrc/core/data/). - Plugin System: Registration, lifecycle management, and ES module loaders (in
src/core/plugins/). - Database Layer: Prisma ORM connecting to PostgreSQL (in
prisma/).
Key Files
src/core/plugins/PluginManager.ts- The PluginManager class. Core registry that instantiates plugins, callsinitialize(), and handles lifecycle events.src/core/plugins/loaders/InstalledPluginsLoader.ts- Dynamically fetches and importsimport(/* 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).
Data Flow
Real-time data follows a strict unidirectional stream optimized for sub-second updates:
- Engine Push: A remote data engine pushes state over WebSocket (
/stream) from a custom backend or our defaultDataEngineV2runner. (Local dev defaults tows://localhost:5001/stream, while cloud fallback iswss://dataenginev2.worldwideview.dev/stream). Seeders in Data Engine V2 expose both a WebSocket stream for real-time instantaneous updates and a REST API endpoint (/api/:id) for fetching live data snapshots. - WebSocket Client Router:
WsClient.handleMessage()receives the payload and pipes it to the event bus. - DataBus Emission: The bus fires
DataBus.emit("websocketData", WsStreamPayload). - State Hydration: The
DataBusSubscribercomponent listens to the bus and calls_hydrateSnapshot()to update the Zustand store'sentitiesByPlugincache. - Memoized Selection:
GlobeViewselects the visible entities from the store. - Primitive Rendering: The
EntityRenderertranslates store entities into CesiumPointPrimitiveCollectionandBillboardCollectionarrays for GPU rendering. - Animation & LOD:
AnimationLoophandles horizon culling and hover effects, whileuseModelRenderingpromotes close-range entities to 3D glTF models.