The Problem

Rendering every road in a city requires pulling large OSM datasets, converting them to a compact format, and drawing millions of line segments in the browser. Developers need a ready‑made visual pipeline that handles data fetching, caching, and WebGL rendering without reinventing the wheel.

What This Does

The repo delivers a single‑page app that queries Overpass or a pre‑built protobuf cache, builds a Three.js‑style scene, and draws all road segments with WebGL. Core logic lives under src/ – for example src/lib/createScene.js creates the renderer, while src/lib/request.js handles network fetches and progress reporting. UI components such as src/components/FindPlace.vue and the color picker live in src/components/. The entry HTML is index.html, and the JavaScript bootstrap is src/main.js.

How It Is Wired

Execution starts at src/main.js, which imports the Vue app (src/App.vue) and calls the scene factory in src/lib/createScene.js. createScene (24 functions, called from three other files) builds the WebGL renderer, registers event handlers from src/createOverlayManager.js and exposes render, clear, getRenderer, and getWGL.

User interaction (e.g., clicking a road) triggers overlay callbacks defined in src/createOverlayManager.js. Those callbacks delegate to the drawing helpers in src/lib/createScene.js (addRect → addPoint is invoked four times).

Data flow begins with src/lib/request.js (7 functions, called from three places). It issues HTTP GETs to the Overpass API or the protobuf cache, updates progress via src/lib/Progress.js, and writes temporary files (the only file‑system interaction in the repo). The response is decoded by src/proto/decode.js and src/proto/encode.js, then transformed into geometry by src/lib/createScene.js.

Search queries are orchestrated by src/lib/Query.js. Its run method (reached via a single call at line 45) constructs a LoadOptions object (src/lib/LoadOptions.js) and triggers the request pipeline.

The most widely used functions are _colorChange, removeOverlay, and request, each called from three distinct locations, giving them the largest blast radius. No circular import cycles were detected, but src/lib/createScene.js imports six other internal modules, making it a hub that must be changed carefully.

How To Use It

# clone the repo
git clone https://github.com/moses-y/city-roads.git
cd city-roads

# install dependencies (npm is declared in package.json)
npm install

# start the development server (hot‑reload on localhost:8080)
npm run dev

# build a production bundle
npm run build

The app runs entirely in the browser; no server‑side configuration or API keys are required beyond the public Overpass endpoint.

Real‑World Use

A municipal data portal could embed the built dist/ bundle as a visual explorer. The portal would pass a city name to the Vue component FindPlace.vue, which internally invokes src/lib/Query.js to fetch and render the road network without any additional backend code.

Code Health & Issues

  • High – No test suite – 40 source files, no test files.
  • High – No CI workflow – repository lacks any GitHub Actions or other CI config.
  • Medium – Dependabot missing – only package.json/package-lock.json present; no .github/dependabot.yml.
  • Medium – High branching density – files src/proto/place.js, src/components/vue3-color/mixin/color.js, src/lib/canvas2BlobPolyfill.js each contain >20 branch points in <45 lines; refactor into smaller, table‑driven units.
  • Medium – Duplicated UI logic – similar 6‑line blocks appear in Alpha.vue, Hue.vue, and Saturation.vue; extract shared helpers to reduce duplication.

The Bottom Line

The project provides a functional, browser‑based road visualizer with a clear separation between data fetching, scene creation, and UI components. However, the lack of tests, CI, and outdated dependencies make it risky for production use without additional engineering effort. It is suitable for prototyping or as a visual demo; teams planning to extend or embed it should first add testing, update the build stack, and address the identified code‑clarity hotspots.