Run request analysis on demand on the VPS

docs/kb/systems/chunk-storage-streaming.md

@@ -0,0 +1,48 @@
+# Chunk Storage And Streaming
+
+## What It Does
+
+World data is stored as per-chunk JSON files and loaded into the editor as chunk neighborhoods around a center chunk. The runtime caches chunk payloads, shifts neighborhoods as the viewport moves, and saves dirty chunks in batches.
+
+## Key Files
+
+- `server.js`
+- `src/worldChunking.ts`
+- `src/worldshaperStudio/bootstrap.ts`
+- `src/worldshaperStudio/runtime.ts`
+- `src/worldshaperStudio/persistenceController.ts`
+
+## Endpoints It Uses
+
+- `GET /api/world/:worldId/chunk/:chunkX/:chunkY`
+- `POST /api/world/:worldId/chunk/:chunkX/:chunkY`
+- `GET /api/world/:worldId/chunks`
+- `POST /api/world/:worldId/chunks/batch-save`
+
+## Important Data And Rules
+
+- chunks are stored as `content/worlds/<worldId>/chunks/<x>_<y>.json`
+- world neighborhoods are requested as a square around a center chunk
+- runtime keeps a chunk cache and tracks dirty chunk keys
+- chunk payloads include `roomLayers`, `heightLayers`, `instances`, and optional `backgroundTileId`
+
+## Invariants And Constraints
+
+- Exact chunk lookup is grid-based and direct.
+- The editor does not load the entire world for normal editing.
+- Small tile edits must sync back into the correct cached chunk.
+- Save flow should preserve chunk-local edits without rebuilding unrelated chunks.
+
+## Common Request Themes
+
+- chunk loading speed
+- chunk streaming behavior
+- per-chunk backgrounds
+- chunk transforms, duplication, deletion
+- performance questions around indexing and caching
+
+## Triage Questions
+
+- Is the request about storage, fetch patterns, cache behavior, or save behavior?
+- Does it affect only visible chunks or the full world?
+- Is the user asking for chunk-local data, or freeform world overlays that break chunk assumptions?