How monsooncollective/yatayat works
Project type and purpose
• Yatayat is a web-based point-to-point public-transport routing application for Kathmandu, built on OpenStreetMap data.
• It includes a static front-end (HTML/CSS/JS), a small Node.js API server, CLI tools for data quality and format conversion, and a Python wrapper to fetch and refresh OSM data.
File structure
Top-level files and directories:
• config*.js, config.overpass.json – configuration for local vs. stable Overpass API access
• api.node.js – Node.js server that exposes route/stop data to the frontend
• datasync.py – Python script that fetches raw OSM via Overpass and orchestrates updates
• cli_dataquality.js – Node.js CLI tool to validate OSM data quality
• dump_gtfs.js – Node.js CLI tool that converts transit XML to GTFS or internal format
• transit.experimental.xml / transit.stable.xml – source data snapshots in OSM XML
• sample/ – example OSM XML and test files
• spec/ – Jasmine tests for the front-end JS logic
• javascripts/, stylesheets/, lib/ – client assets (Leaflet, kdTree, Underscore, Bootstrap, custom CSS/JS)
• index.html, data_quality.html, tests.html – entry points for the app, quality report, and test runner
Extract architectural hints from the README
• Data Model: OSM data → Routes, Stops, Segments
• Workflow: git submodules → config → data quality checks → periodic Overpass fetch → transform → serve to client
Main components and interactions
A. Data Ingestion Pipeline
1. External Overpass API service (pull raw OSM XML)
2. datasync.py orchestrates download and invokes cli_dataquality.js
3. cli_dataquality.js validates data; on pass, passes XML to dump_gtfs.js
4. dump_gtfs.js outputs GTFS files or internal JSON (transit*.xml) and commits to Git
B. Data Store
• Git repository holds transit XML snapshots, sample data, config files
C. API Server
• api.node.js reads processed transit XML/JSON and serves HTTP endpoints (e.g., /routes, /stops)
D. Front-End Client
• index.html + javascripts/main.js
• Uses Leaflet to render map, kdTree for nearest-stop lookup, Underscore for data handling
• Fetches JSON data from the API server or bundled config endpoints
E. External Services
• Overpass API (for OSM data)
• (Optional) Email service for alerts in datasync.py
Architectural patterns and design principles
• Clear separation of concerns: data ingestion and validation (CLI & Python) vs. serving data (Node) vs. UI (static JS)
• “Git as a database” for versioning processed transit XML
• Client-side routing computations using spatial index (kdTree)
• Config-driven environment selection (config.local.js vs. config.stable.json)