# pauligwe/ubermaps architecture

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

- Interactive diagram: https://gitdiagram.com/pauligwe/ubermaps
- Repository: https://github.com/pauligwe/ubermaps

## Overview

1. **Overall shape**
   - This is a two-tier Node/React app with a thin browser frontend and a backend orchestration API.
   - The backend owns all routing, geographic calculations, and third-party API calls; the frontend is mainly a UI for inputs, map display, and result rendering.
   - There is no persistent database or long-lived domain store; each route search is a request-driven computation.

2. **Frontend boundary**
   - `frontend/` is a Vite-built React application.
   - `App.jsx` is the main UI composition point: city selector, origin/destination/budget/departure inputs, map, and results panel.
   - The frontend submits a route-planning request to the backend and renders the returned hybrid/full-transit options and map geometry.

3. **Backend entrypoint**
   - `backend/index.js` starts the Express server.
   - It applies security-related middleware and serves the compiled frontend assets in production, so the backend is also the web server.
   - This means the deployed system is typically a single origin: browser UI plus API from one Node process.

4. **API boundary**
   - `backend/routes/route.js` exposes the main application endpoint, `POST /api/route`.
   - This route is responsible for request validation and then dispatching into the route-planning pipeline.
   - The API contract is centered around trip planning inputs: origin, destination, budget, departure time, and city context.

5. **City and pricing model**
   - `backend/services/cities.js` defines supported cities and their local configuration, including geographic center, timezone, and fare rates.
   - `backend/services/fareEstimate.js` converts budget into an approximate Uber reach using the city’s pricing model and surge multiplier.
   - This pricing layer is central to the architecture because it determines the search radius and whether a candidate handoff stop is even feasible.

6. **Candidate discovery**
   - `backend/services/places.js` queries Google Places for transit stops within the budget-derived search area.
   - This is the first external lookup in the pipeline and is used to generate candidate handoff points rather than relying on preloaded station data.
   - The result is a dynamic set of possible switch points between ride-share and transit.

7. **Baseline transit comparison**
   - `backend/services/google.js` uses Google Directions in transit mode to compute the full public-transit baseline and later validate candidate hybrid routes.
   - The baseline route is important because the app only prefers a hybrid option if it arrives meaningfully earlier than full transit.
   - This service is also the source of the transit legs returned to the UI for map display.

8. **Road-distance filtering**
   - `backend/services/osrm.js` uses OSRM for driving/road distance and duration, plus route geometry/polyline data.
   - OSRM acts as a fast filter before more expensive transit validation: candidates that would exceed budget or are effectively walkable from the destination are removed.
   - This creates a clear computational boundary: road-network estimation first, then transit confirmation.

9. **Orchestration pipeline**
   - `backend/services/pipeline.js` coordinates the full algorithm and enforces the overall timeout.
   - The pipeline follows the sequence described in the README: radius calculation, stop discovery, OSRM filtering, Google transit validation, and winner selection.
   - It is the main business-logic boundary in the repository, and most architecture diagrams should treat it as the core engine.

10. **Selection logic and output**
   - The winner is the hybrid route with the earliest arrival time that beats the full-transit baseline by at least five minutes.
   - If no candidate wins, the system falls back to the full-transit route and reports that transit is faster.
   - The response includes the chosen handoff stop, estimated Uber fare, comparison against the baseline, and route geometry for visualization.

11. **External services**
   - The backend depends on Google Maps APIs for Places and Directions.
   - It also depends on OSRM for routing calculations and Mapbox for frontend map tiles/rendering, based on the required token.
   - These integrations are the main external architecture dependencies and should be shown explicitly in any diagram.

12. **Execution model**
   - The system is synchronous from the user’s perspective, but internally it fans out across external services and candidate evaluations.
   - The computational bottleneck is in the backend pipeline, not in the frontend.
   - Because there is no database, caching layer, or message queue in the repo, all state is transient per request.

13. **What to draw in an architecture diagram**
   - A browser client sends trip-planning inputs to an Express API.
   - The API invokes a route-planning pipeline that reads city config, computes budget/radius, queries Google Places, filters with OSRM, validates with Google Directions, and returns the best route.
   - The same backend also serves the built React frontend assets to the browser.

Main entry points: [`backend/services/pipeline.js`](https://github.com/pauligwe/ubermaps/blob/main/backend/services/pipeline.js) (Planner), [`frontend/src/App.jsx`](https://github.com/pauligwe/ubermaps/blob/main/frontend/src/App.jsx) (App UI), [`backend/index.js`](https://github.com/pauligwe/ubermaps/blob/main/backend/index.js) (Express server), [`backend/services/google.js`](https://github.com/pauligwe/ubermaps/blob/main/backend/services/google.js) (Google adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser<br/>client"))
  node_app["App UI<br/>react shell<br/>[App.jsx]"]
end

subgraph group_backend["Backend"]
  node_server["Express server<br/>web server<br/>[index.js]"]
  node_routeapi["Route API<br/>http route<br/>[route.js]"]
  node_pipeline{{"Planner<br/>orchestrator<br/>[pipeline.js]"}}
  node_cities["Cities<br/>config model<br/>[cities.js]"]
  node_fare["Fare estimate<br/>pricing<br/>[fareEstimate.js]"]
  node_places["Place search<br/>candidate discovery<br/>[places.js]"]
  node_osrm["Road filter<br/>routing filter<br/>[osrm.js]"]
  node_google["Google adapter<br/>maps integration<br/>[google.js]"]
  node_transit["Transit baseline<br/>comparison result"]
  node_winner{{"Winner selection<br/>decision logic"}}
  node_response["Route result<br/>api payload"]
end

subgraph group_external["External services"]
  node_mapbox(("Mapbox<br/>maps tiles"))
  node_gplaces(("Google Places<br/>external api"))
  node_gdirections(("Google Directions<br/>external api"))
  node_osrmext(("OSRM<br/>external router"))
end

node_browser -->|"opens"| node_app
node_app -->|"POST /api/route"| node_server
node_server -->|"routes"| node_routeapi
node_routeapi -->|"invokes"| node_pipeline
node_server -->|"serves build"| node_app
node_app -->|"renders map"| node_mapbox
node_pipeline -->|"reads"| node_cities
node_pipeline -->|"computes radius"| node_fare
node_fare -->|"uses pricing"| node_cities
node_pipeline -->|"discovers stops"| node_places
node_places -->|"queries"| node_gplaces
node_pipeline -->|"filters candidates"| node_osrm
node_osrm -->|"routes"| node_osrmext
node_pipeline -->|"validates"| node_google
node_google -->|"transit mode"| node_gdirections
node_google -->|"returns baseline"| node_transit
node_pipeline -->|"selects"| node_winner
node_winner -->|"formats"| node_response
node_response -->|"renders"| node_app
node_response -->|"delivers"| node_browser

click node_app "https://github.com/pauligwe/ubermaps/blob/main/frontend/src/App.jsx"
click node_server "https://github.com/pauligwe/ubermaps/blob/main/backend/index.js"
click node_routeapi "https://github.com/pauligwe/ubermaps/blob/main/backend/routes/route.js"
click node_pipeline "https://github.com/pauligwe/ubermaps/blob/main/backend/services/pipeline.js"
click node_cities "https://github.com/pauligwe/ubermaps/blob/main/backend/services/cities.js"
click node_fare "https://github.com/pauligwe/ubermaps/blob/main/backend/services/fareEstimate.js"
click node_places "https://github.com/pauligwe/ubermaps/blob/main/backend/services/places.js"
click node_osrm "https://github.com/pauligwe/ubermaps/blob/main/backend/services/osrm.js"
click node_google "https://github.com/pauligwe/ubermaps/blob/main/backend/services/google.js"

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_browser,node_app toneBlue
class node_server,node_routeapi,node_pipeline,node_cities,node_fare,node_places,node_osrm,node_google,node_transit,node_winner,node_response toneAmber
class node_mapbox,node_gplaces,node_gdirections,node_osrmext toneMint
```

## Components

### Frontend

Browser UI and map rendering

- **Browser**: client · User-facing entry point
- [App UI](https://github.com/pauligwe/ubermaps/blob/main/frontend/src/App.jsx): react shell · Main trip-planning interface · `frontend/src/App.jsx`

### Backend

Express API and route-planning engine

- [Express server](https://github.com/pauligwe/ubermaps/blob/main/backend/index.js): web server · Hosts API and serves built frontend · `backend/index.js`
- [Route API](https://github.com/pauligwe/ubermaps/blob/main/backend/routes/route.js): http route · Main planning endpoint · `backend/routes/route.js`
- [Planner](https://github.com/pauligwe/ubermaps/blob/main/backend/services/pipeline.js): orchestrator · Coordinates the route-selection workflow · `backend/services/pipeline.js`
- [Cities](https://github.com/pauligwe/ubermaps/blob/main/backend/services/cities.js): config model · Supported cities and local pricing context · `backend/services/cities.js`
- [Fare estimate](https://github.com/pauligwe/ubermaps/blob/main/backend/services/fareEstimate.js): pricing · Budget to ride-share reach calculation · `backend/services/fareEstimate.js`
- [Place search](https://github.com/pauligwe/ubermaps/blob/main/backend/services/places.js): candidate discovery · Finds transit stops near the search area · `backend/services/places.js`
- [Road filter](https://github.com/pauligwe/ubermaps/blob/main/backend/services/osrm.js): routing filter · Driving distance, duration, and geometry · `backend/services/osrm.js`
- [Google adapter](https://github.com/pauligwe/ubermaps/blob/main/backend/services/google.js): maps integration · Transit baseline and validation calls · `backend/services/google.js`
- **Transit baseline**: comparison result · Full public-transit route used as benchmark
- **Winner selection**: decision logic · Chooses hybrid route or falls back to transit
- **Route result**: api payload · Chosen handoff, fare, comparison, and geometry

### External services

Third-party APIs and routing engines

- **Mapbox**: maps tiles · Map rendering and tiles
- **Google Places**: external api · Transit stop discovery
- **Google Directions**: external api · Transit routing and validation
- **OSRM**: external router · Road-network routing service

## Connections

- Browser → App UI: opens · Loads the trip-planning interface
- App UI → Express server: POST /api/route · Sends trip inputs to the backend
- Express server → Route API: routes · Express dispatches the planning request
- Route API → Planner: invokes · Hands off validated request parameters
- Express server → App UI: serves build · Returns compiled frontend assets in production
- App UI → Mapbox: renders map · Displays route geometry and map layers
- Planner → Cities: reads · Loads city center, timezone, and fare rates
- Planner → Fare estimate: computes radius · Converts budget into ride-share reach
- Fare estimate → Cities: uses pricing · Applies city-specific fare model
- Planner → Place search: discovers stops · Finds candidate handoff points
- Place search → Google Places: queries · Searches Google Places for transit stops
- Planner → Road filter: filters candidates · Removes infeasible or walkable options
- Road filter → OSRM: routes · Requests driving distance, duration, and geometry
- Planner → Google adapter: validates · Checks candidate routes against transit travel time
- Google adapter → Google Directions: transit mode · Computes public-transit directions
- Google adapter → Transit baseline: returns baseline · Produces the full-transit comparison route
- Planner → Winner selection: selects · Chooses earliest hybrid that beats transit by threshold
- Winner selection → Route result: formats · Builds the final response payload
- Route result → App UI: renders · UI shows results and map geometry
- Route result → Browser: delivers · User receives the planned route outcome