# strandedkitty/streets-gl architecture

> Architecture diagram of the GitHub repository strandedkitty/streets-gl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strandedkitty/streets-gl
- Repository: https://github.com/strandedkitty/streets-gl

## Overview

Streets GL is a browser-based real-time 3D OpenStreetMap viewer. Users navigate or search a map location; the application loads vector tiles and terrain, converts map features into renderable geometry, and displays the scene with configurable time and visual effects. The graph follows the documented data sources and capabilities and the sampled application, worker, and feature-handler code. Several subsystem connections are documented or suggested by the tree rather than verified in sampled implementations, so uncertain call-level links are omitted.

Main entry points: [`src/app/systems/TileObjectsSystem.ts`](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/TileObjectsSystem.ts) (Map scene objects), [`src/app/world/worker/WorkerInstance.ts`](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/world/worker/WorkerInstance.ts) (Tile worker), [`src/app/ui/UI.tsx`](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/ui/UI.tsx) (Map interface), [`src/app/systems/RenderSystem.ts`](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/RenderSystem.ts) (Render orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Viewer experience"]
  node_app["App lifecycle<br/>[App.ts]"]
  node_ui["Map interface<br/>[UI.tsx]"]
  node_controls["Navigation<br/>[ControlsSystem.ts]"]
  node_search["Global search<br/>[SearchPanel.tsx]"]
  node_settings["Settings<br/>[SettingsSystem.ts]"]
  node_time["Map time<br/>[MapTimeSystem.ts]"]
end

subgraph group_mapdata["Map data"]
  node_tiles["Tile loading"]
  node_tile_server{{"Tile server"}}
  node_worker_system["Worker coordination<br/>[MapWorkerSystem.ts]"]
  node_worker["Tile worker<br/>[WorkerInstance.ts]"]
  node_vector_provider["Vector tile provider"]
  node_vector_processing["OSM feature processing"]
end

subgraph group_scene["Scene construction"]
  node_terrain["Terrain heights<br/>[TerrainSystem.ts]"]
  node_geometry["3D geometry"]
  node_scene_objects["Map scene objects"]
  node_vehicles["Air traffic<br/>[VehicleSystem.ts]"]
end

subgraph group_render["Rendering"]
  node_render_system["Render orchestration<br/>[RenderSystem.ts]"]
  node_passes["Render passes<br/>[Pass.ts]"]
  node_effects["Visual effects<br/>[TAAPass.ts]"]
end

subgraph group_engine["Graphics engine"]
  node_render_graph["Render graph<br/>[RenderGraph.ts]"]
  node_webgl["WebGL2 renderer<br/>[WebGL2Renderer.ts]"]
end

node_user(("Map viewer"))
node_nominatim{{"Nominatim"}}

node_user -->|"interacts"| node_ui
node_ui -->|"changes view"| node_controls
node_ui -->|"searches"| node_search
node_search -.->|"queries"| node_nominatim
node_app -->|"initializes"| node_ui
node_app -->|"updates systems"| node_render_system
node_tiles -->|"requests tiles"| node_tile_server
node_tiles -->|"dispatches tiles"| node_worker_system
node_worker_system -->|"assigns work"| node_worker
node_worker -->|"loads features"| node_vector_provider
node_vector_provider -->|"processes OSM"| node_vector_processing
node_worker -->|"requests heights"| node_terrain
node_worker -->|"converts features"| node_geometry
node_terrain -->|"supplies terrain"| node_scene_objects
node_geometry -->|"creates features"| node_scene_objects
node_vehicles -->|"adds aircraft"| node_scene_objects
node_time -->|"sets time"| node_scene_objects
node_settings -->|"configures rendering"| node_render_system
node_scene_objects -->|"supplies scene"| node_render_system
node_render_system -->|"runs passes"| node_passes
node_passes -->|"registers work"| node_render_graph
node_render_graph -->|"executes passes"| node_webgl
node_passes -->|"includes effects"| node_effects

click node_app "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/App.ts"
click node_ui "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/ui/UI.tsx"
click node_controls "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/ControlsSystem.ts"
click node_search "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/ui/components/SearchPanel/SearchPanel.tsx"
click node_settings "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/SettingsSystem.ts"
click node_time "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/MapTimeSystem.ts"
click node_tiles "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/TileLoadingSystem.ts"
click node_worker_system "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/MapWorkerSystem.ts"
click node_worker "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/world/worker/WorkerInstance.ts"
click node_vector_provider "https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/tile-processing/tile3d/providers/Tile3DFromVectorProvider.ts"
click node_vector_processing "https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/tile-processing/vector/handlers/OSMRelationHandler.ts"
click node_terrain "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/TerrainSystem.ts"
click node_geometry "https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/tile-processing/tile3d/handlers/VectorAreaHandler.ts"
click node_scene_objects "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/TileObjectsSystem.ts"
click node_vehicles "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/VehicleSystem.ts"
click node_render_system "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/RenderSystem.ts"
click node_passes "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/render/passes/Pass.ts"
click node_effects "https://github.com/strandedkitty/streets-gl/blob/dev/src/app/render/passes/TAAPass.ts"
click node_render_graph "https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/render-graph/RenderGraph.ts"
click node_webgl "https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/renderer/webgl2-renderer/WebGL2Renderer.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_ui,node_controls,node_search,node_settings,node_time,node_user toneBlue
class node_tiles,node_tile_server,node_worker_system,node_worker,node_vector_provider,node_vector_processing toneAmber
class node_terrain,node_geometry,node_scene_objects,node_vehicles toneMint
class node_render_system,node_passes,node_effects toneRose
class node_render_graph,node_webgl,node_nominatim toneIndigo
```

## Components

### Viewer experience

- [App lifecycle](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/App.ts): `src/app/App.ts`
- [Map interface](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/ui/UI.tsx): `src/app/ui/UI.tsx`
- [Navigation](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/ControlsSystem.ts): `src/app/systems/ControlsSystem.ts`
- [Global search](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/ui/components/SearchPanel/SearchPanel.tsx): `src/app/ui/components/SearchPanel/SearchPanel.tsx`
- [Settings](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/SettingsSystem.ts): `src/app/systems/SettingsSystem.ts`
- [Map time](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/MapTimeSystem.ts): `src/app/systems/MapTimeSystem.ts`

### Map data

- [Tile loading](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/TileLoadingSystem.ts): `src/app/systems/TileLoadingSystem.ts`
- **Tile server**
- [Worker coordination](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/MapWorkerSystem.ts): `src/app/systems/MapWorkerSystem.ts`
- [Tile worker](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/world/worker/WorkerInstance.ts): `src/app/world/worker/WorkerInstance.ts`
- [Vector tile provider](https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/tile-processing/tile3d/providers/Tile3DFromVectorProvider.ts): `src/lib/tile-processing/tile3d/providers/Tile3DFromVectorProvider.ts`
- [OSM feature processing](https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/tile-processing/vector/handlers/OSMRelationHandler.ts): `src/lib/tile-processing/vector/handlers/OSMRelationHandler.ts`

### Scene construction

- [Terrain heights](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/TerrainSystem.ts): `src/app/systems/TerrainSystem.ts`
- [3D geometry](https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/tile-processing/tile3d/handlers/VectorAreaHandler.ts): `src/lib/tile-processing/tile3d/handlers/VectorAreaHandler.ts`
- [Map scene objects](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/TileObjectsSystem.ts): `src/app/systems/TileObjectsSystem.ts`
- [Air traffic](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/VehicleSystem.ts): `src/app/systems/VehicleSystem.ts`

### Rendering

- [Render orchestration](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/systems/RenderSystem.ts): `src/app/systems/RenderSystem.ts`
- [Render passes](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/render/passes/Pass.ts): `src/app/render/passes/Pass.ts`
- [Visual effects](https://github.com/strandedkitty/streets-gl/blob/dev/src/app/render/passes/TAAPass.ts): `src/app/render/passes/TAAPass.ts`

### Graphics engine

- [Render graph](https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/render-graph/RenderGraph.ts): `src/lib/render-graph/RenderGraph.ts`
- [WebGL2 renderer](https://github.com/strandedkitty/streets-gl/blob/dev/src/lib/renderer/webgl2-renderer/WebGL2Renderer.ts): `src/lib/renderer/webgl2-renderer/WebGL2Renderer.ts`

### Other components

- **Map viewer**
- **Nominatim**

## Connections

- Map viewer → Map interface: interacts
- Map interface → Navigation: changes view
- Map interface → Global search: searches
- Global search → Nominatim: queries
- App lifecycle → Map interface: initializes
- App lifecycle → Render orchestration: updates systems
- Tile loading → Tile server: requests tiles
- Tile loading → Worker coordination: dispatches tiles
- Worker coordination → Tile worker: assigns work
- Tile worker → Vector tile provider: loads features
- Vector tile provider → OSM feature processing: processes OSM
- Tile worker → Terrain heights: requests heights
- Tile worker → 3D geometry: converts features
- Terrain heights → Map scene objects: supplies terrain
- 3D geometry → Map scene objects: creates features
- Air traffic → Map scene objects: adds aircraft
- Map time → Map scene objects: sets time
- Settings → Render orchestration: configures rendering
- Map scene objects → Render orchestration: supplies scene
- Render orchestration → Render passes: runs passes
- Render passes → Render graph: registers work
- Render graph → WebGL2 renderer: executes passes
- Render passes → Visual effects: includes effects
