Files
worldwideview/docs/ARCHITECTURE.md
T
silvertakana 932713e7a2 docs: sync public docs to current implementation
- SETUP.md: npm  pnpm, remove internal .agents/ from folder tree, replace webpack HMR note with DB tip
- ARCHITECTURE.md: fix 'Abstration' typo
- creating-a-plugin.md: replace 'edit knownPlugins.ts' step (internal) with correct npm submission flow, npm  pnpm commands, update flow diagram to match actual marketplace arch
2026-03-30 14:17:15 +13:00

3.1 KiB

System Architecture

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.

Module Breakdown

  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.).

Performance: Primitives vs. Entities

One of our core design decisions is using Cesium Primitives instead of the standard high-level Entity API for high-count datasets.

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:

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.