Safe2Go — Logic, Databases & APIs

flowchart LR
  U["User: web app / iOS / Android"] --> S["Safe2Go server
Node.js/Express on Railway
safe2go.dnw-ai.com"]
  S --> M[("MongoDB
users, journeys, credits,
GPS pings, alerts")]
  S --> G[("Postgres: gtfs  (505 GB)
timetables, search index,
flights, buildings")]
  S --> O[("Postgres: osm_transit  (285 GB)
transit stops, OSM addresses,
route cache")]
  S --> MG[("Postgres: mobility_graph  (435 MB)
modes per place, currency")]
  S --> V["Valhalla road routing
8 regions, self-hosted"]
  S --> T["Map tiles (pmtiles)
self-hosted"]
  S --> X["External APIs
geocoding, traffic, POI,
OSRM, Overpass, AI, payments"]
  subgraph H["Hetzner server (self-hosted, owned)"]
    G
    O
    MG
    V
    T
  end

flowchart TD
  Q["User types: 'Hauptstrasse 12, Mannheim'"] --> P{{"Query 4 sources in parallel"}}
  P --> A["1. locality_alias
(gtfs DB)
places other users confirmed"]
  P --> I["2. place_search_index
(gtfs DB, 27.2M rows)
OUR OWN index"]
  P --> PH["3. Photon (komoot)
EXTERNAL, free"]
  P --> MP["4. Mappls
EXTERNAL, India only, metered"]
  A --> MR["Merge + rank:
alias > own index > Mappls > Photon"]
  I --> MR
  PH --> MR
  MP --> MR
  MR --> E{"Enough good results?"}
  E -- yes --> R["Return top results"]
  E -- no --> F["Fallback chain:
Nominatim → Mappls → LocationIQ → OpenCage → TomTom
(all EXTERNAL, tried one by one)"]
  F --> R
  R --> B["Optional: snap to nearest real building
google_open_building / ms_building_footprint
(gtfs DB, 671M buildings)"]

flowchart TD
  IN["INPUT: start + end coordinates, departure time, maxModes (1-3)"]
  IN --> S1["STEP 1 — gather facts, all at the same time
1. Road distance/time + 'does a road exist?' — Valhalla (own) → OSRM (external) → straight line × 1.3
2. Nearest rail/tram/metro station WITH timetable — gtfs: stops, stop_route_types
3. Nearest bus stop WITH timetable — gtfs: stops, stop_route_types
4. Nearest bus / metro / ferry / airport stops — osm_transit: transit_stops
5. Auto-rickshaw/taxi available? hours? currency? — mobility_graph"]
  S1 --> OV{"Nothing local found
near start or end?"}
  OV -- yes --> OVP["Overpass API (external) — LAST RESORT, that point only"]
  OV -- no --> A
  OVP --> A
  A["STEP 2 — build candidate routes, in this order
A. LIVE direct timetable trip today
findDirectTrip → stop_times, trips, calendar + live delays"]
  A --> B["B. LIVE trip with 1 change — findTransferTrip"]
  B --> C{"A found a live trip?"}
  C -- no --> C2["C. SCHEDULED — findPrecomputedConnection → route_connections
(trips/day + sample departure)"]
  C -- yes --> D
  C2 --> D["D. HEURISTIC local bus / metro — nearest stops + estimate"]
  D --> E["E. HEURISTIC train — only 8-120 km, heavy-rail station at BOTH ends, same region"]
  E --> F["F. FERRY — direct terminals (real water shortcut) or via curated ferry hub"]
  F --> G["G. FLIGHT — hub airports + route confirmed in flight_routes (see section 4)"]
  G --> H["H. DIRECT taxi / auto / car / bike / walk — only if a real road exists and no ferry needed"]
  H --> X["STEP 3 — reject anything invented
heuristic route > 3× real road distance → dropped
rejectFabricatedRoutes()"]
  X --> Z{"Any route left?"}
  Z -- no --> NR["noReliableRoute = true — tell the user, never guess"]
  Z -- yes --> T["STEP 4 — buildJourneyTimeline()
time per leg, airport buffers, time zones"]
  T --> OUT["Route options shown to the user"]

flowchart TD
  A["resolveRoadRoute(start, end)"] --> B{"Both points inside the SAME
built Valhalla region?"}
  B -- yes --> V["Valhalla (own, Hetzner)
regions: germany, india, usa, msb,
australia, canada, africa, europe"]
  B -- no --> O["OSRM public demo server
(external, no SLA)"]
  V --> VF{"Valhalla says:
no road connects them?"}
  VF -- yes --> NR["connectorUnavailable = true
no taxi/car option offered"]
  VF -- no --> OK["distance + time
+ hasFerry / ferryKm"]
  O --> OK2["distance + time
(fallback: straight line × 1.3)"]
  OK --> TR["× traffic realism factor
1.5 (<15km) … 1.15 (>200km)"]
  OK2 --> TR
  TR --> C[("route_cache (osm_transit)
persists results across restarts")]

flowchart TD
  A["Riding: tram / bus / metro / train (real timetable trip)
next leg = scheduled departure, e.g. Bus 45 at 20:10"] --> B["Where is the vehicle on its trip, how late?
operator live delay (GTFS-Realtime) OR
user GPS vs that trip's own timetable"]
  B --> C["Predicted arrival at the change stop
= scheduled arrival + delay"]
  C --> D["Connection's own status
live delay / cancelled (if published)
otherwise assumed on time"]
  D --> E["Spare time = connection departure
− predicted arrival − walk between stops
− minimum change time (bus/tram/metro 2 · train 4 · ferry 20 · air 90 min)"]
  E --> F{"Spare time?"}
  F -- "3 min or more" --> OK["✅ On track for the Bus 45 at 20:10"]
  F -- "0–3 min" --> T["⏱ Tight change — about N min to spare
+ safer options (safety net)"]
  F -- "below 0, or connection cancelled" --> M["🚨 You'll miss the Bus 45 at 20:10
(or 🚫 cancelled)"]
  T --> S
  M --> S["Stations still ahead: next 1–3 + the planned change stop
with the time the vehicle reaches each"]
  S --> P["From EACH station, at THAT time:
full route search (subway / bus / tram / cab / walk / next bus)
own car & bike excluded"]
  P --> R["Rank by arrival at destination
varied: best public transport · best cab · best walk"]
  R --> U["'Get off at X (next stop, ~20:05) → Taxi → arrive 20:16'
[Use this]"]
  U --> N["Journey switches to: stay on to X → new legs
Safety Mode follows the new route"]

flowchart TD
  S["Trip distance > 100 km"] --> Q{"Intercontinental
OR > 500 km
OR airport near start?"}
  Q -- no --> N["No flight option"]
  Q -- yes --> H["Pick up to 2 departure airports + 2 arrival airports
curated hub list (~140 major airports)
+ OSM airports from transit_stops
sanity: airport must be < 500 km from the point"]
  H --> G{"Arrival airport has a real ROAD
to the destination (no sea crossing)?"}
  G -- no --> X["Airport rejected
(Malta/Tunis fix)"]
  G -- yes --> F{"flight_routes + flight_airlines:
documented route for THIS exact
airport pair?"}
  F -- no --> N2["No flight offered
(no guessing — no fallback airline table)"]
  F -- yes --> L["Flight leg + real airline names
+ Google Flights booking link"]
  L --> GR["Ground legs to/from airports:
1) live timetable (findDirectTrip / findTransferTrip)
2) coach terminal if both ends < 60 km
3) taxi / auto"]
  GR --> T["Timeline: check-in buffer, arrival buffer"]

flowchart LR
  subgraph NOW["TODAY — external"]
    A1["Photon / Nominatim /
LocationIQ / OpenCage / TomTom Search"]
    A2["Mappls (India hyperlocal)"]
    A3["Overpass, Geoapify, Foursquare"]
    A4["OSRM public server"]
    A5["TomTom Traffic / Google Directions"]
    A6["ipwho.is"]
  end
  subgraph OWN["TARGET — own data (Hetzner)"]
    B1["place_search_index
+ world OSM addresses per country
+ street-names pass + buildings"]
    B2["locality_alias (user-confirmed)
+ India Post / LGD / India OSM"]
    B3["transit_stops (all countries)
+ GTFS stops"]
    B4["Valhalla for every region"]
    B5["Own traffic model
(no decided source yet)"]
    B6["Local IP-to-country database"]
  end
  A1 -->|"as country imports finish"| B1
  A2 -->|"slowest — proprietary data"| B2
  A3 -->|"as transit_stops coverage grows"| B3
  A4 -->|"build remaining regions"| B4
  A5 -.->|"hardest, open question"| B5
  A6 --> B6

flowchart TD
  subgraph SRC["Sources (downloaded)"]
    S1["Geofabrik OSM extracts (.osm.pbf)
per country/continent"]
    S2["GTFS feeds (operators,
MobilityDatabase.org)"]
    S3["OpenFlights routes/airlines"]
    S4["India Post, LGD, GeoNames"]
    S5["Google Open Buildings,
MS Building Footprints"]
  end
  S1 -->|"osm2pgsql + world_address_import.lua
(one table per country)"| T1[("world_osm_addresses_*
world_osm_localities_*")]
  S1 -->|"india_address_import.lua"| T2[("india_osm_*")]
  S1 -->|"stop extraction"| T3[("transit_stops")]
  S1 -->|"valhalla_build_tiles"| T4["Valhalla tiles (8 regions)"]
  S2 -->|"GTFS ingest"| T5[("stops, stop_times, trips,
routes, calendar, agencies, feeds")]
  T5 -->|"build_route_connections.sh
(self-join over stop_times)"| T6[("route_connections")]
  T5 -->|"lookup build"| T7[("stop_route_types")]
  S3 --> T8[("flight_routes, flight_airlines")]
  S4 --> T9[("postal_office, lgd_*, geonames_*")]
  S5 --> T10[("google_open_building,
ms_building_footprint")]
  T1 --> IDX["build_place_search_index.js"]
  T2 --> IDX
  T9 --> IDX
  IDX --> T11[("place_search_index")]

flowchart TD
  OS["SAFE2GO GLOBAL MOBILITY OS"] --> PM["PLACE MASTER"]
  OS --> MM["MOBILITY MASTER"]
  PM --> AD["Address"]
  PM --> RD["Road"]
  PM --> POI["POI"]
  MM --> RA["Rail"]
  MM --> BU["Bus"]
  MM --> AI["Air"]
  MM --> FE["Ferry"]
  AD --> GNG["GLOBAL NODE GRAPH
one ID system for every place, stop, station, airport, port, border crossing"]
  RD --> GNG
  POI --> GNG
  RA --> GNG
  BU --> GNG
  AI --> GNG
  FE --> GNG
  GNG --> RRG["Regional Road Graphs
(Valhalla per region)"]
  GNG --> SC["Scheduled Connections
(rail, bus, air, ferry timetables)"]
  RRG --> IG["INTERMODAL GRAPH"]
  SC --> IG
  IG --> TE["TRANSFER ENGINE
is this change physically possible, and how long does it take?"]
  TE --> TDR["TIME-DEPENDENT ROUTE ENGINE"]
  TDR --> JR["Journey Ranking"]
  TDR --> VA["Validation
(no invented data)"]
  JR --> OUT["Safe2Go Route"]
  VA --> OUT

flowchart TD
  A["User enters: Plot 130, Satyam Enclave, Sahibabad → Kathmandu"] --> B["ADDRESS → local coordinates
(own search index)"]
  B --> C["Nearest road / bus stop
(own PostGIS)"]
  C --> D["India road / transit network
(Valhalla India + GTFS)"]
  D --> E["Delhi airport / railway / bus terminal
(global node)"]
  E --> F["International connection
(flight or bus edge, from schedule master)"]
  F --> G["Nepal network"]
  G --> H["Kathmandu"]
  H --> I["Final local road / transit leg"]

flowchart LR
  G1["Germany graph"] -->|"border node"| G2["Austria graph"] -->|"border node"| G3["Italy graph"]

flowchart TD
  S1["User input"] --> S2["Normalize"] --> S3["Exact index"] --> S4["Prefix index"] --> S5["Token index"] --> S6["Fuzzy index"] --> S7["Spatial index"] --> S8["Alias index"] --> S9["Building / road / locality match"]

flowchart TD
  P1["GPS"] --> P2["Nearest road"] --> P3["Nearest locality"] --> P4["Nearest building"] --> P5["Address evidence"] --> P6["Confidence score
(never invent a plot number)"]