Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
50f685b223 |
No files matched your search
@@ -64,7 +64,12 @@ worldwideview/
|
||||
│ ├── types/ # GeoJSON types, Umami types
|
||||
│ └── generated/ # Prisma generated client (gitignored)
|
||||
├── packages/ # pnpm monorepo workspace packages
|
||||
│ ├── create-wwv-plugin/ # CLI scaffold generator for new plugins
|
||||
│ ├── wwv-data-engine/ # Standalone data microservice backend
|
||||
│ ├── wwv-plugin-sdk/ # Plugin SDK: type definitions, manifest schema
|
||||
│ ├── wwv-lib-aviation/ # Shared aviation utilities
|
||||
│ ├── wwv-lib-facilities/
|
||||
│ ├── wwv-lib-incidents/
|
||||
│ ├── wwv-plugin-aviation/
|
||||
│ ├── wwv-plugin-maritime/
|
||||
│ ├── wwv-plugin-wildfire/
|
||||
@@ -73,10 +78,16 @@ worldwideview/
|
||||
│ ├── wwv-plugin-military-aviation/
|
||||
│ ├── wwv-plugin-satellite/
|
||||
│ ├── wwv-plugin-iranwarlive/ # Includes standalone backend/ microservice
|
||||
│ └── wwv-plugin-{airports,embassies,lighthouses,nuclear,seaports,spaceports,volcanoes}/
|
||||
│ ├── wwv-plugin-air-defense/
|
||||
│ ├── wwv-plugin-conflict-zones/
|
||||
│ ├── wwv-plugin-military-bases/
|
||||
│ ├── wwv-plugin-mineral-mines/
|
||||
│ └── wwv-plugin-{airports,civil-unrest,conflict-events,cyber-attacks,daynight,
|
||||
│ earthquakes,embassies,gps-jamming,international-sanctions,lighthouses,
|
||||
│ nuclear,seaports,spaceports,surveillance-satellites,undersea-cables,volcanoes}/
|
||||
├── prisma/ # schema.prisma, migrations/
|
||||
├── public/ # Static assets, Cesium workers, plugin GeoJSON data
|
||||
├── scripts/ # Build scripts (copy-cesium, scaffold-osm-plugin, setup)
|
||||
├── scripts/ # Build scripts (copy-cesium, setup, convertCameras)
|
||||
├── data/ # SQLite database (gitignored, Docker volume)
|
||||
├── Dockerfile # Multi-stage production build
|
||||
├── docker-compose.yml # Main app + microservice backends
|
||||
@@ -235,7 +246,7 @@ pnpm test # Run all Vitest tests (scoped to src/lib, src/core, src/p
|
||||
pnpm db:reset # Reset and re-migrate the frontend SQLite database (destructive)
|
||||
pnpm start:backends # Start all plugin microservice backends in parallel
|
||||
pnpm clean:backends # Wipe all plugin SQLite databases
|
||||
pnpm run scaffold-osm-plugin <name> # Generate a new plugin from scaffold
|
||||
pnpm exec create-wwv-plugin <name> # Generate a new plugin from scaffold
|
||||
```
|
||||
|
||||
Frontend runs at `http://localhost:3000`.
|
||||
|
||||
+6
-7
@@ -30,15 +30,15 @@ This project is licensed under the [Elastic License 2.0](./LICENSE). By submitti
|
||||
```
|
||||
3. **Install dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
pnpm install
|
||||
```
|
||||
4. **Generate environment file** (auto-creates `.env.local` with `AUTH_SECRET`):
|
||||
```bash
|
||||
npm run setup
|
||||
pnpm run setup
|
||||
```
|
||||
5. **Start the dev server**:
|
||||
```bash
|
||||
npm run dev
|
||||
pnpm run dev:all
|
||||
```
|
||||
|
||||
Visit `http://localhost:3000` to confirm everything is running.
|
||||
@@ -50,7 +50,7 @@ Visit `http://localhost:3000` to confirm everything is running.
|
||||
| Requirement | Version |
|
||||
|-------------|---------|
|
||||
| Node.js | 18+ |
|
||||
| npm | 9+ |
|
||||
| pnpm | 8+ |
|
||||
|
||||
See [`docs/SETUP.md`](docs/SETUP.md) for detailed environment setup, including Cesium Ion token configuration.
|
||||
|
||||
@@ -134,7 +134,7 @@ refactor: extract billboard factory from CesiumMap
|
||||
## Pull Request Process
|
||||
|
||||
1. Ensure your branch is up to date with `main`.
|
||||
2. Run tests and confirm they pass: `npm test`
|
||||
2. Run tests and confirm they pass: `pnpm test`
|
||||
3. Fill out the [PR template](.github/PULL_REQUEST_TEMPLATE.md) completely.
|
||||
4. Request a review — PRs need at least one approval before merging.
|
||||
5. Squash commits on merge if the history is noisy.
|
||||
@@ -144,8 +144,7 @@ refactor: extract billboard factory from CesiumMap
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
npm test # Run all tests via Vitest
|
||||
npm run test:ui # Open Vitest UI (interactive)
|
||||
pnpm test # Run all tests via Vitest
|
||||
```
|
||||
|
||||
Tests live alongside source files in `__tests__/` directories or as `.test.ts` files.
|
||||
@@ -24,7 +24,7 @@ Ready to add a new intelligence layer (like Earthquakes, Weather, or Satellites)
|
||||
|
||||
```bash
|
||||
# 1. Generate the boilerplate plugin from a template
|
||||
pnpm run scaffold-osm-plugin my-new-data-source
|
||||
pnpm exec create-wwv-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!
|
||||
@@ -77,6 +77,8 @@ When deploying to production, ensure you mount the following volumes to prevent
|
||||
|
||||
- **[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.
|
||||
- **[Plugin Guide](docs/PLUGIN_GUIDE.md)**: Full walkthrough for building custom data layer plugins.
|
||||
- **[API Reference](docs/API_REFERENCE.md)**: Technical reference for internal services (DataBus, PluginRegistry, CacheLayer).
|
||||
- **[Contributions Guide](CONTRIBUTING.md)**: How to help out, coding standards, and commit conventions.
|
||||
- **[User Guide](docs/USER_GUIDE.md)**: Application features and navigation tips.
|
||||
|
||||
|
||||
+21
-11
@@ -4,7 +4,10 @@ WorldWideView is a high-performance, event-driven geospatial intelligence engine
|
||||
|
||||
## Module Breakdown
|
||||
|
||||
1. **`src/core/plugins`**: The registration and lifecycle management layer. Defines how plugins are booted and destroyed.
|
||||
1. **`src/core/plugins`**: The registration and lifecycle management layer. Defines how plugins are booted and destroyed. Three plugin architectures are supported:
|
||||
- **Static** — GeoJSON file in `public/data/`, loaded by `StaticDataPlugin`
|
||||
- **Active Proxied** — Next.js API routes in `src/app/api/` acting as a CORS proxy
|
||||
- **Microservice** — Standalone Fastify container with SQLite (e.g., `iranwarlive-backend`)
|
||||
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.
|
||||
@@ -12,6 +15,8 @@ WorldWideView is a high-performance, event-driven geospatial intelligence engine
|
||||
3. **`src/core/globe`**: The Rendering Engine.
|
||||
- **Cesium Integration**: Low-level control over the Cesium Viewer.
|
||||
- **EntityRenderer**: High-performance "Primitive" renderer.
|
||||
- **AnimationLoop**: Horizon culling, hover/selection at 60FPS.
|
||||
- **StackManager**: Groups co-located entities and handles spiderification.
|
||||
4. **`src/plugins`**: Domain-specific logic (Aviation, Maritime, etc.).
|
||||
|
||||
## Performance: Primitives vs. Entities
|
||||
@@ -29,24 +34,29 @@ One of our core design decisions is using **Cesium Primitives** instead of the s
|
||||
|
||||
## Data Pipeline (Example: Aviation)
|
||||
|
||||
The following diagram trace the journey of a single data point from a remote sensor to the user's screen:
|
||||
The following diagram traces the journey of a single data point from the data engine to the user's screen. WorldWideView uses a **WebSocket push model** — the data engine streams updates to the client over a persistent `/stream` connection, eliminating the need for repeated HTTP polling:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant S as Remote API (e.g. OpenSky)
|
||||
participant P as Plugin (AviationPlugin)
|
||||
participant E as Data Engine (/stream)
|
||||
participant W as WsClient (DataBusSubscriber)
|
||||
participant D as DataBus
|
||||
participant S as Zustand Store
|
||||
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
|
||||
Note over E, W: Visibility Toggle (layer enabled)
|
||||
W->>E: subscribe to layer via WebSocket
|
||||
loop On data push
|
||||
E->>W: snapshot payload (WsStreamPayload)
|
||||
rect rgb(200, 230, 255)
|
||||
Note right of W: Hydrate snapshot
|
||||
W->>W: _hydrateSnapshot()
|
||||
end
|
||||
W->>D: emit("dataUpdated", { pluginId, entities })
|
||||
D->>S: Store.entitiesByPlugin update
|
||||
end
|
||||
P->>D: emit("dataUpdated", { entities })
|
||||
D->>R: trigger render cycle
|
||||
S->>R: memoized visible entities
|
||||
rect rgb(255, 230, 200)
|
||||
Note right of R: Batch Update Primitives
|
||||
R->>G: update collection buffer
|
||||
|
||||
@@ -130,7 +130,7 @@ export class EarthquakePlugin implements WorldPlugin {
|
||||
|
||||
### Register Your Plugin
|
||||
|
||||
In your app's initialization code (e.g. the root layout component):
|
||||
Built-in plugins are registered in `src/components/layout/AppShell.tsx`. Add your plugin instantiation there alongside the existing ones:
|
||||
|
||||
```typescript
|
||||
import { pluginRegistry } from "@/core/plugins/PluginRegistry";
|
||||
|
||||
+1
-1
@@ -26,7 +26,7 @@ The HUD at the top provides real-time information about your current view:
|
||||
### 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.
|
||||
- **Playback Controls**: If supported by the plugin, you can scrub through historical data.
|
||||
|
||||
## Interacting with Entities
|
||||
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "worldwideview",
|
||||
"version": "1.7.1",
|
||||
"version": "1.7.2",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"setup": "node scripts/setup.mjs",
|
||||
|
||||
Reference in new issue
Block a user