Compare commits

...
Author SHA1 Message Date
Claude 50f685b223 docs: update documentation for accuracy and consistency
- CONTRIBUTING.md: replace npm with pnpm throughout; remove nonexistent test:ui script
- docs/ARCHITECTURE.md: fix grammar, update data pipeline diagram to reflect WebSocket push model, expand module breakdown with plugin architecture types and rendering components
- docs/PLUGIN_GUIDE.md: point plugin registration to AppShell.tsx
- docs/USER_GUIDE.md: fix grammar ("scrubbing" → "scrub")
- README.md: fix scaffold command (pnpm exec create-wwv-plugin), add Plugin Guide and API Reference to docs index
- AGENTS.md: correct scripts/ listing, add all 34 packages, fix scaffold command
- package.json: bump version 1.7.1 → 1.7.2

https://claude.ai/code/session_01JYDygaWX2ZW6TeU5Fmekfy
2026-04-13 11:38:57 +00:00
7 changed files with 47 additions and 25 deletions

No files matched your search

+14 -3
View File
@@ -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
View File
@@ -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.
+3 -1
View File
@@ -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
View File
@@ -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
+1 -1
View File
@@ -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
View File
@@ -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
View File
@@ -1,6 +1,6 @@
{
"name": "worldwideview",
"version": "1.7.1",
"version": "1.7.2",
"private": true,
"scripts": {
"setup": "node scripts/setup.mjs",