From 3f642f5079315eb5171e9adaea71028b826ac2ee Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sat, 12 Sep 2026 13:04:16 -0700 Subject: [PATCH] docs: describe focused local service ownership --- CHANGELOG.md | 4 ++++ CONTRIBUTING.md | 4 ++-- SECURITY.md | 4 ++-- docs/CODE-BOUNDARIES.md | 27 ++++++++++++++++++++++----- docs/CURRENT-STATE.md | 27 ++++++++++++++++++++++++--- 5 files changed, 54 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ac9ef983..96eb6d91c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,10 @@ of current runtime behavior, see [`docs/CURRENT-STATE.md`](docs/CURRENT-STATE.md ## [Unreleased] +- Split Overpass/installation search, regional briefing/weather, local voice + handlers and standalone key setup into focused modules. Preserve routes, + source behavior, tool schemas and credential restrictions. + - Restore data-provider routes under local build preview and return JSON 404s for unmatched API requests. Credential editing remains development-only. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 84f7d0c76..b765948ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,7 @@ The highest-leverage places to jump in: - **🌆 Add a CCTV source pack.** Austin is the reference camera source. Adding another city means a clean public camera catalog with coordinates, attribution, and server-registered frame URLs (the proxy only fetches registered URLs — never client-supplied ones, see [SECURITY.md](SECURITY.md)). City packs are the best first lane. - **🛰️ Add or improve a data layer.** Each layer is one self-contained module in `src/data/.js` implementing the layer interface (`init/enable/disable/update/destroy/getStats`, optional `getDetectableObjects`/`getStats`). Use an existing layer as a template. -- **🎙️ Extend voice control.** Voice tools are declared server-side (`GEV_REALTIME_TOOLS` in `server/providers/local.js`) and executed client-side (`src/voice/gevActions.js`). Keep the tool surface tight and the responses honest (confirm only what actually happened). +- **🎙️ Extend voice control.** Voice tools are declared server-side (`GEV_REALTIME_TOOLS` in `server/providers/openai/tools.js`) and executed client-side (`src/voice/gevActions.js`). Keep the tool surface tight and the responses honest (confirm only what actually happened). - **🎨 Add a visual style.** Styles are GLSL post-process shaders in `src/styles/`. - **🐛 Fix bugs / improve the first-run experience.** See [docs/KNOWN-ISSUES.md](docs/KNOWN-ISSUES.md). @@ -51,7 +51,7 @@ The highest-leverage places to jump in: - **No framework.** Vanilla JS + [CesiumJS](https://cesium.com/platform/cesiumjs/) + [Vite](https://vitejs.dev/). - **UI lives in `src/ui.js`** (panels, HUD, styles, the control facade). **Layer logic lives in `src/data/.js`.** Keep them separate. -- **Secrets stay server-side.** Anything needing a private key goes through a local proxy in `server/providers/local.js`. The browser only ever sees the Google Maps key (which you restrict) and ephemeral tokens. +- **Secrets stay server-side.** Anything needing a private key goes through a local proxy under `server/providers/`. The browser only ever sees the Google Maps key (which you restrict) and ephemeral tokens. - `docs/CURRENT-STATE.md` is the authoritative runtime reference — read it first. ## Coding style diff --git a/SECURITY.md b/SECURITY.md index d19a5446d..20fee1a36 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -13,7 +13,7 @@ Include repro steps and impact. We'll acknowledge, investigate, and credit you ( ## How secrets are handled -The golden rule: **secret-bearing API keys stay on the server side.** The dev/preview server (middleware in `server/providers/local.js`) brokers every request that needs a private credential, so the browser never receives one. +The golden rule: **secret-bearing API keys stay on the server side.** The dev/preview server (middleware under `server/providers/`) brokers every request that needs a private credential, so the browser never receives one. | Key | Where it lives | How the browser uses it | |-----|----------------|--------------------------| @@ -59,7 +59,7 @@ browser-key fallback for existing single-key setups. ## Server-side proxy hardening -The data proxies in `server/providers/local.js` are written so the browser cannot turn the server into an open relay: +The data proxies under `server/providers/` are written so the browser cannot turn the server into an open relay: - **No arbitrary-URL fetching.** The CCTV frame proxy fetches only server-registered camera/frame URLs — clients cannot pass an upstream URL to fetch (SSRF mitigation). Other proxies target fixed upstream hosts. - **Radio is not an audio relay.** `/api/radio/stations` contacts only allowlisted Radio Browser HTTPS hosts and paths, rejects redirects, rejects any hostname with a loopback/private/link-local/metadata/non-public A or AAAA result, and pins each TLS connection to a validated address. It returns normalized public HTTPS stream URLs; `/api/radio/click/:uuid` applies the same destination policy and accepts only station IDs from the current bounded catalog. The browser then connects directly to the broadcaster after an explicit playback action, so the broadcaster sees the listener's IP address. GEV never proxies, caches, records, or redistributes audio. diff --git a/docs/CODE-BOUNDARIES.md b/docs/CODE-BOUNDARIES.md index 5fbdba635..0811dba85 100644 --- a/docs/CODE-BOUNDARIES.md +++ b/docs/CODE-BOUNDARIES.md @@ -79,11 +79,10 @@ use build-only dependency exceptions. `server/standalone/vite.config.js` loads the root environment and passes selected browser keys, host/port and the ordered local provider plugins to this helper. -`server/providers/local.js` still owns provider process state, routes and -credential-store paths. Provider Settings writes to the same root `.env` or -Pinokio store as before. `vite.config.js` preserves the default configuration and -existing named provider exports for tools/tests. The provider module remains -large; later extractions should split complete provider families and their tests. +`server/providers/local.js` composes provider factories and re-exports existing +helpers for compatibility. Provider Settings lives in `server/standalone/key-setup.js` +and writes to the same root `.env` or Pinokio store as before. `vite.config.js` +preserves the default configuration and named provider exports for tools/tests. ## Aircraft and vessel providers @@ -152,3 +151,21 @@ checks each entry independently. Browser terrain sampling, traffic matching/drawing, fire overlays and bike-share layer lifecycle remain in their current modules. This extraction changes no source defaults, credentials, quotas, data interpretation or visual behavior. + +## Local search, regional context, voice and setup + +Node-only exports `server/providers/overpass`, `server/providers/military-installations`, +`server/providers/regional` and `server/providers/openai` own request handling +without importing the standalone configuration or browser rendering. Overpass +separates query admission, geometry simplification, cache and transport; military +search shares the bounded transport. Regional place/news/weather acquisition is +separate from briefing and weather-effect response caches. Voice handlers share +existing rate limits and request reading; schemas and instructions are separate. + +`server/standalone/key-setup` is explicitly standalone Node functionality. +Its factory and the local voice factory accept `sourceRoot` for application-owned +configuration/log files; defaults resolve the repository root. Local voice also +accepts an optional `annotationGuidance` paragraph. Neither factory starts +acquisition on import. Setup retains its pre-environment-load provenance capture +and development-only registration. Package checks enumerate every owned module +and reject browser imports of these Node entries. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 48ffa78b8..65caab7a7 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1,5 +1,26 @@ # God's Eye View Current State +## Remaining local service modules + +Overpass query validation, geometry simplification, disk caching and upstream +transport now have separate modules; military-installation search reuses that +transport. Regional briefing combines separate place, news and weather sources, +while weather effects uses only the weather source. Existing process-scoped +caches, rate limits, stale fallbacks and route ordering are preserved. + +Local voice has separate HUD-summary, debug-log and Realtime-token handlers, +with tool definitions and instructions in dedicated files. The factory accepts +an optional `annotationGuidance` paragraph; its default instructions and all 28 +tool definitions remain unchanged. `sourceRoot` resolves debug logs against the +application directory. Standalone key setup accepts the same directory option +for its environment store and preserves boot provenance, loopback/origin guards, +atomic credential writes and development-only registration. + +Node-only package entries expose Overpass, military installations, regional +services, local voice and standalone key setup. Importing them starts no network +acquisition. Browser layer lifecycle, rendering and voice execution stay in their +existing modules. + ## Local build preview After `npm run build`, `npm run preview` serves the built app with the same data @@ -55,10 +76,10 @@ access. Callers retain validation, transport and response policy. `vite.config.js` delegates to `server/standalone/vite.config.js`, which loads this checkout's environment and constructs the local providers in their existing -order. `server/providers/local.js` holds the existing middleware and process -state; its named exports remain available through the root compatibility entry. +order. `server/providers/local.js` is the composition and compatibility entry; +provider families own their middleware and process state in focused modules. Provider URLs, key selection, cache behavior, setup restrictions and routes are -unchanged. Individual provider families remain to be split into smaller modules. +unchanged. `gods-eye-view/build/vite` is a Node-only export for explicit browser build settings: Cesium assets, caller-supplied plugins, browser key defines, server