63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# 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) |
|
|
|---|---|---|
|
|
| **Abstration** | 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.
|