# monsooncollective/yatayat architecture

> Architecture diagram of the GitHub repository monsooncollective/yatayat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monsooncollective/yatayat
- Repository: https://github.com/monsooncollective/yatayat

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Ingestion"
        OSM["Overpass API"]:::external
        DS["datasync.py (Python)"]:::ingestion
        QL["cli_dataquality.js"]:::ingestion
        GT["dump_gtfs.js"]:::ingestion
        Email["Email Service"]:::external
        OSM -->|"OSM XML"| DS
        DS -->|"invoke"| QL
        QL -->|"valid? pass"| GT
        QL -->|"fail: alert"| Email
    end

    subgraph "Data Store"
        TE["transit.experimental.xml"]:::datastore
        TS["transit.stable.xml"]:::datastore
        Sample["sample/"]:::datastore
        GT -->|"update snapshots"| TE
        GT -->|"update snapshots"| TS
    end

    subgraph "API & Services"
        ConfigLocal["config.local.js"]:::api
        ConfigOver["config.overpass.json"]:::api
        ConfigStable["config.stable.json"]:::api
        ConfigExp["config.experimental.json"]:::api
        ConfigJs["config.js"]:::api
        Api["api.node.js"]:::api
        TE -->|"reads XML/JSON"| Api
        TS -->|"reads XML/JSON"| Api
    end

    subgraph "Client UI"
        Browser["Web Browser"]:::external
        FEIndex["index.html"]:::frontend
        FEQ["data_quality.html"]:::frontend
        FETests["tests.html"]:::frontend
        FEBh["bhadadar.html"]:::frontend
        FEO["osmroutenames.html"]:::frontend
        MainJs["javascripts/main.js"]:::frontend
        RespondJs["javascripts/respond.js"]:::frontend
        DataQualityJs["dataquality.js"]:::frontend
        libLeaf["lib/leaflet/..."]:::frontend
        libKd["lib/kdTree-min.js"]:::frontend
        libUnd["lib/underscore-min.js"]:::frontend
        libBoot["lib/bootstrap/"]:::frontend
        libY["lib/yatayat.css"]:::frontend
        Styles["stylesheets/"]:::frontend
        Specs["spec/"]:::frontend

        Api -->|"HTTP JSON"| FEIndex
        FEIndex -->|"uses"| MainJs
        FEIndex --> RespondJs
        FEIndex -->|"UI mapping"| libLeaf
        FEIndex --> libKd
        FEIndex --> libUnd
        FEIndex --> libBoot
        FEIndex --> libY
        FEIndex --> Styles
        Browser --> FEIndex
        FETests --> Specs
    end

    classDef ingestion fill:#fffa65,stroke:#333,stroke-width:1px;
    classDef datastore fill:#dddddd,stroke:#333,stroke-width:1px;
    classDef api fill:#65caff,stroke:#333,stroke-width:1px;
    classDef frontend fill:#a8ffa8,stroke:#333,stroke-width:1px;
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px;

    click DS "https://github.com/monsooncollective/yatayat/blob/gh-pages/datasync.py"
    click QL "https://github.com/monsooncollective/yatayat/blob/gh-pages/cli_dataquality.js"
    click GT "https://github.com/monsooncollective/yatayat/blob/gh-pages/dump_gtfs.js"
    click ConfigLocal "https://github.com/monsooncollective/yatayat/blob/gh-pages/config.local.js"
    click ConfigOver "https://github.com/monsooncollective/yatayat/blob/gh-pages/config.overpass.json"
    click ConfigStable "https://github.com/monsooncollective/yatayat/blob/gh-pages/config.stable.json"
    click ConfigExp "https://github.com/monsooncollective/yatayat/blob/gh-pages/config.experimental.json"
    click ConfigJs "https://github.com/monsooncollective/yatayat/blob/gh-pages/config.js"
    click TE "https://github.com/monsooncollective/yatayat/blob/gh-pages/transit.experimental.xml"
    click TS "https://github.com/monsooncollective/yatayat/blob/gh-pages/transit.stable.xml"
    click Sample "https://github.com/monsooncollective/yatayat/tree/gh-pages/sample/"
    click Api "https://github.com/monsooncollective/yatayat/blob/gh-pages/api.node.js"
    click FEIndex "https://github.com/monsooncollective/yatayat/blob/gh-pages/index.html"
    click FEQ "https://github.com/monsooncollective/yatayat/blob/gh-pages/data_quality.html"
    click FETests "https://github.com/monsooncollective/yatayat/blob/gh-pages/tests.html"
    click FEBh "https://github.com/monsooncollective/yatayat/blob/gh-pages/bhadadar.html"
    click FEO "https://github.com/monsooncollective/yatayat/blob/gh-pages/osmroutenames.html"
    click MainJs "https://github.com/monsooncollective/yatayat/blob/gh-pages/javascripts/main.js"
    click RespondJs "https://github.com/monsooncollective/yatayat/blob/gh-pages/javascripts/respond.js"
    click DataQualityJs "https://github.com/monsooncollective/yatayat/blob/gh-pages/dataquality.js"
    click libLeaf "https://github.com/monsooncollective/yatayat/blob/gh-pages/lib/leaflet/leaflet.js"
    click libKd "https://github.com/monsooncollective/yatayat/blob/gh-pages/lib/kdTree-min.js"
    click libUnd "https://github.com/monsooncollective/yatayat/blob/gh-pages/lib/underscore-min.js"
    click libBoot "https://github.com/monsooncollective/yatayat/tree/gh-pages/lib/bootstrap/"
    click libY "https://github.com/monsooncollective/yatayat/blob/gh-pages/lib/yatayat.css"
    click Styles "https://github.com/monsooncollective/yatayat/tree/gh-pages/stylesheets/"
    click Specs "https://github.com/monsooncollective/yatayat/tree/gh-pages/spec/"
```
