doc: update readme

README.md

@@ -19,8 +19,6 @@ BullMQ Worker (pipeline queue, concurrency 8)
   ├── refresh-city      → orchestrates full ingest via FlowProducer
   ├── download-pbf      → streams OSM PBF from Geofabrik
   ├── extract-pois      → osmium filter + osm2pgsql flex → raw_pois
-  ├── build-valhalla    → clips PBF, builds Valhalla routing tiles + transit tiles
-  ├── download-gtfs-de  → downloads & extracts GTFS feed for German ÖPNV
   ├── generate-grid     → PostGIS 200 m hex grid → grid_points
   ├── compute-scores    → two-phase orchestrator (see Scoring below)
   ├── compute-routing   → Valhalla matrix → grid_poi_details
@@ -28,15 +26,26 @@ BullMQ Worker (pipeline queue, concurrency 8)
   └── compute-transit   → Valhalla isochrones → grid_poi_details (travel_mode='transit')
                            (1 job per city, covers all categories via PostGIS spatial join)
 
-BullMQ Worker (valhalla queue, concurrency 1)
+BullMQ Worker (valhalla queue, concurrency 1) — road-only instance
-  └── build-valhalla   → valhalla_ingest_transit + valhalla_convert_transit (GTFS → tiles),
+  └── build-valhalla   → osmium clip + valhalla_build_tiles (road graph only, no transit
-                          valhalla_build_tiles (road graph + transit connection),
+                          connections) → manages valhalla_service on :8002
-                          manages valhalla_service
+                          Clean tiles ensure cycling/walking/driving routing is never
+                          affected by ghost edges from failed transit connections.
 
-Valhalla (child process of valhalla worker)
+BullMQ Worker (valhalla-transit queue, concurrency 1) — transit instance
+  ├── download-gtfs-de → downloads & filters GTFS feed for German ÖPNV (bbox-clipped to
+  │                       known cities, single-stop trips removed)
+  └── build-valhalla   → osmium clip + valhalla_ingest_transit + valhalla_convert_transit
+                          + valhalla_build_tiles (road graph with transit connections)
+                          → manages valhalla_service on :8002 (separate container/port)
+
+Valhalla road instance (child process of valhalla worker, port 8002)
   ├── sources_to_targets matrix → compute-routing jobs (walking/cycling/driving)
-  ├── isochrone (multimodal)    → compute-transit jobs
+  └── isochrone endpoint        → user click → /api/isochrones (non-transit modes)
-  └── isochrone endpoint        → user click → /api/isochrones
+
+Valhalla transit instance (child process of valhalla-transit worker, port 8002)
+  ├── isochrone (multimodal) → compute-transit jobs
+  └── isochrone endpoint     → user click → /api/isochrones (transit mode)
 
 Protomaps → self-hosted map tiles (PMTiles)
 ```
@@ -184,7 +193,7 @@ When a user places a pin on the map:
 1. The nearest grid point is found via a PostGIS `<->` KNN query.
 2. Precomputed `grid_scores` rows for that grid point, travel mode, threshold, and profile are returned — one row per category.
 3. Per-subcategory detail rows from `grid_poi_details` are also fetched, showing the name, straight-line distance, and travel time to the nearest POI in each subcategory for the requested mode.
-4. An isochrone overlay is fetched live from Valhalla and shown on the map (walking is used as the representative mode for `fifteen` and `transit` since Valhalla's interactive isochrone only supports single-mode costing).
+4. An isochrone overlay is fetched live from Valhalla and shown on the map. For `transit` mode the multimodal isochrone comes from the dedicated transit Valhalla instance. For `fifteen` (Best mode), cycling is used as the representative display isochrone since Valhalla's interactive isochrone only supports single-mode costing.
 
 The pin panel also shows estate value data (land price in €/m² from the BORIS NI cadastre) for cities in Lower Saxony, including a percentile rank among all zones in the city and a "peer percentile" rank among zones with similar accessibility scores.