Files
worldwideview/docs/ARCHITECTURE.md
T
Silvertakana c4207bd6e1 feat(core): migrate to Prisma 7 and unify PostgreSQL architecture (#56)
* feat(cloud): implement Postgres DB adapter, fix static build crashes, and containerize NextAuth/Stripe integrations

* test(marketplace): fix mocks and assertions for multi-tenant Postgres architecture

* feat: rsa jwt license key verification and state integration

* feat: add internal workspace validation route for Edge Functions

* refactor: clean up hub routes and finalize db proxy/adapter for multi-tenant cloud deploy

* feat(cloud): finalize multi-tenant Prisma extensions and workspace routing

* fix(db): correct Prisma 7 better-sqlite3 adapter initialization [Patch]

- update better-sqlite3 adapter instantiation to use configuration object ({ url }) required by Prisma 7 instead of raw Database instance [Patch]
- fix PrismaClientConstructorValidationError by generating client with adapter support [Patch]

* fix(auth): support dynamic origins for local proxies and multi-tenant subdomains [Patch]

- prioritize forwarded headers and request host over hardcoded envOrigin in getRequestOrigin to support subdomain routing [Patch]
- allow ALLOWED_DEV_ORIGIN in marketplace install redirect checks to fix local network development login flows [Patch]

* fix(marketplace): enable dynamic CORS reflection for marketplace API [Patch]

- remove explicit origin array, replacing with origin header reflection to allow marketplace hosted on any domain or local IP [Patch]

- remove global wildcard CORS headers from next.config.ts to harden security against broader app injection [Patch]

* feat(db): create initial postgresql migration

* refactor(db): update remaining files for postgresql

* feat(db): unify database adapter to PostgreSQL-only [Minor]

- replace SQLite adapter with PostgreSQL PrismaPg [Minor]
- remove better-sqlite3 dependencies [Patch]
- finalize docs and implementation plan [Patch]

* fix: resolve prisma client generation and script execution issues with tsx and type module

* feat(db): port tenant isolation logic to new PostgreSQL adapter

* docs: add rule for transparent and narrated agent actions

* BREAKING CHANGE(core): migrate to PostgreSQL and add auto-migration pipeline [Major]

- unified database adapter to exclusively use PostgreSQL [Major]
- implement auto-migration pipeline to pipe legacy SQLite data to Postgres [Major]
- add sqlite to runner stage to support extraction pipeline [Patch]

* feat(core): migrate to Prisma 7 and unify PostgreSQL architecture [Minor]

- removed legacy Prisma SQLite driver and all Better-Sqlite dependencies [Minor]
- updated schema to utilize purely postgresql providers [Patch]
- modified migration scripts to seamlessly convert local sqlite DBs to PostgreSQL containers using keinos/sqlite3 [Minor]
- updated deployment scripts, Coolify pipelines, and Nginx proxy support [Patch]
- injected Prisma Client Extensions for multi-tenant Row Level Security isolation [Minor]
- stabilized PrismaClient initialization utilizing the official adapter-pg runtime pattern [Patch]
- bumped version to 2.1.0

* fix(core): resolve TypeScript compilation errors for CI [Patch]

- fixed NextResponse.json() 3-arg calls to use 2-arg ResponseInit form [Patch]
- replaced invalid 'developer' TrustTier with 'unverified' in parseWwvManifest and load-unpacked route [Patch]
- removed non-existent pluginManager.hotReload() call in DevModeSubscriber, replaced with disable/reload cycle [Patch]
- updated Stripe API version from '2024-04-10' to '2026-04-22.dahlia' to match installed SDK [Patch]
- excluded local-scripts/ from tsconfig to prevent debug scripts from breaking CI [Patch]

* fix(ci): resolve pnpm version conflict in GitHub Actions [Patch]

- removed explicit version: 9 from pnpm/action-setup@v4 — v4 auto-reads packageManager from package.json [Patch]
- updated build job DATABASE_URL from SQLite to PostgreSQL format [Patch]

* fix(docker): add explicit Prisma generator output path for Docker builds [Patch]

- Prisma 7 changed default output location, causing COPY --from=builder to fail
- added output = '../src/generated/prisma' to generator block for consistency

* fix(prisma): update client import path and resolve CI type errors [Patch]

- updated PrismaClient import in db.ts to point to custom generated output path
- resolved implicit 'any' error in marketplace check-updates route
- verified clean local build with tsc --noEmit

* chore(deps): sync Prisma versions to 7.6.0 [Patch]
2026-05-09 22:44:30 +12:00

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

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 (in src/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, calls initialize(), and handles lifecycle events.
  • src/core/plugins/loaders/InstalledPluginsLoader.ts - Dynamically fetches and imports import(/* 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:

  1. Engine Push: A remote data engine pushes state over WebSocket (/stream) from either local seeders (ws://localhost:5001/stream) or the cloud fallback (wss://dataengine.worldwideview.dev/stream).
  2. WebSocket Client Router: WsClient.handleMessage() receives the payload and pipes it to the event bus.
  3. DataBus Emission: The bus fires DataBus.emit("websocketData", WsStreamPayload).
  4. State Hydration: The DataBusSubscriber component listens to the bus and calls _hydrateSnapshot() to update the Zustand store's entitiesByPlugin cache.
  5. Memoized Selection: GlobeView selects the visible entities from the store.
  6. Primitive Rendering: The EntityRenderer translates store entities into Cesium PointPrimitiveCollection and BillboardCollection arrays for GPU rendering.
  7. Animation & LOD: AnimationLoop handles horizon culling and hover effects, while useModelRendering promotes close-range entities to 3D glTF models.