# elpiratilla/bus-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/elpiratilla/bus-tracker
- Repository: https://github.com/elpiratilla/bus-tracker

## Overview

go503 is a live San Salvador bus tracker with passenger arrival estimates and alerts, a fleet-owner management panel, driver GPS tracking, and ESP32 telemetry. The main flow is bus location reporting into server-side tracking, route status and ETA calculation, then passenger map/arrival information; fleet management and family tracking are additional product branches. The README documents product capabilities, while some frontend and family-link wiring is not shown in the sampled source, so those connections are marked unverified.

Main entry points: [`src/server.js`](https://github.com/elpiratilla/bus-tracker/blob/main/src/server.js) (Express server), [`src/tracking.js`](https://github.com/elpiratilla/bus-tracker/blob/main/src/tracking.js) (Trip tracking), [`src/routes/empresa.js`](https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/empresa.js) (Fleet API), [`src/routes/telemetry.js`](https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/telemetry.js) (Telemetry API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User experiences"]
  node_map_ui["Live map<br/>[mapa.js]"]
  node_fleet_ui["Fleet panel<br/>[panel.js]"]
  node_login_ui["Company access<br/>[acceso.js]"]
  node_web_push["Push worker<br/>[sw.js]"]
  node_lead_form["Sensor inquiry<br/>[landing.js]"]
  node_school_tracking["Private school tracking<br/>[mapa.js]"]
end

subgraph group_api["Server API"]
  node_server["Express server<br/>[server.js]"]
  node_telemetry_api["Telemetry API<br/>[telemetry.js]"]
  node_routes_api["Routes API<br/>[rutas.js]"]
  node_alerts_api["Alerts API<br/>[alertas.js]"]
  node_company_api["Fleet API<br/>[empresa.js]"]
  node_clients_api["Lead API<br/>[clientes.js]"]
  node_driver_api["Driver API<br/>[motorista.js]"]
  node_auth["Sensor auth<br/>[auth.js]"]
  node_company_auth["Company auth<br/>[empresa.js]"]
end

subgraph group_tracking["Transit processing"]
  node_eta["ETA engine<br/>[eta.js]"]
  node_tracking_logic["Trip tracking<br/>[tracking.js]"]
  node_route_shapes["Route geometry<br/>[trazos.js]"]
  node_geo["Geo calculations<br/>[geo.js]"]
  node_state["Transit state<br/>[store.js]"]
  node_database[("Supabase<br/>[db.js]")]
  node_alerts["Arrival alerts<br/>[alerts.js]"]
end

subgraph group_devices["Location sources"]
  node_sensor["ESP32 sensor"]
  node_driver_app["Driver app<br/>[motorista.js]"]
end

node_passenger(("Passenger"))
node_fleet_owner(("Fleet owner"))
node_family(("Family"))
node_driver(("Driver"))

node_passenger -->|"views buses"| node_map_ui
node_map_ui -.->|"requests route status"| node_routes_api
node_routes_api -->|"calculates arrivals"| node_eta
node_eta -->|"reads transit state"| node_state
node_eta -->|"measures distance"| node_geo
node_passenger -->|"receives arrival alerts"| node_web_push
node_web_push -.->|"subscribes"| node_alerts_api
node_alerts_api -->|"manages alerts"| node_alerts
node_alerts -->|"estimates arrivals"| node_eta
node_alerts -->|"reads alert state"| node_state
node_fleet_owner -->|"signs in"| node_login_ui
node_fleet_owner -->|"manages fleet"| node_fleet_ui
node_fleet_ui -.->|"manages units"| node_company_api
node_fleet_ui -.->|"views route data"| node_routes_api
node_company_api -->|"checks company session"| node_company_auth
node_company_api -->|"edits route shapes"| node_route_shapes
node_company_api -->|"reads and writes fleet data"| node_database
node_driver -->|"starts bus tracking"| node_driver_app
node_driver_app -.->|"reports trip"| node_driver_api
node_sensor -->|"sends bus data"| node_telemetry_api
node_telemetry_api -->|"checks sensor key"| node_auth
node_telemetry_api -->|"updates trip tracking"| node_tracking_logic
node_driver_api -->|"controls trips"| node_tracking_logic
node_tracking_logic -->|"records GPS traces"| node_route_shapes
node_tracking_logic -->|"finds nearby stops"| node_geo
node_tracking_logic -->|"persists trip data"| node_database
node_tracking_logic -->|"updates trip state"| node_state
node_server -->|"mounts endpoint"| node_telemetry_api
node_server -->|"mounts endpoint"| node_routes_api
node_server -->|"mounts endpoint"| node_alerts_api
node_server -->|"mounts endpoint"| node_company_api
node_server -->|"mounts endpoint"| node_clients_api
node_server -->|"mounts endpoint"| node_driver_api
node_server -->|"loads saved state"| node_database
node_fleet_owner -->|"requests sensor"| node_lead_form
node_lead_form -.->|"submits inquiry"| node_clients_api
node_family -->|"views private location"| node_school_tracking

click node_sensor "https://github.com/elpiratilla/bus-tracker/tree/main/firmware/go503_sensor"
click node_driver_app "https://github.com/elpiratilla/bus-tracker/blob/main/public/js/motorista.js"
click node_map_ui "https://github.com/elpiratilla/bus-tracker/blob/main/public/js/mapa.js"
click node_fleet_ui "https://github.com/elpiratilla/bus-tracker/blob/main/public/js/panel.js"
click node_login_ui "https://github.com/elpiratilla/bus-tracker/blob/main/public/js/acceso.js"
click node_web_push "https://github.com/elpiratilla/bus-tracker/blob/main/public/sw.js"
click node_server "https://github.com/elpiratilla/bus-tracker/blob/main/src/server.js"
click node_telemetry_api "https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/telemetry.js"
click node_routes_api "https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/rutas.js"
click node_alerts_api "https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/alertas.js"
click node_company_api "https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/empresa.js"
click node_clients_api "https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/clientes.js"
click node_driver_api "https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/motorista.js"
click node_auth "https://github.com/elpiratilla/bus-tracker/blob/main/src/middleware/auth.js"
click node_company_auth "https://github.com/elpiratilla/bus-tracker/blob/main/src/middleware/empresa.js"
click node_eta "https://github.com/elpiratilla/bus-tracker/blob/main/src/eta.js"
click node_tracking_logic "https://github.com/elpiratilla/bus-tracker/blob/main/src/tracking.js"
click node_route_shapes "https://github.com/elpiratilla/bus-tracker/blob/main/src/trazos.js"
click node_geo "https://github.com/elpiratilla/bus-tracker/blob/main/src/geo.js"
click node_state "https://github.com/elpiratilla/bus-tracker/blob/main/src/store.js"
click node_database "https://github.com/elpiratilla/bus-tracker/blob/main/src/db.js"
click node_alerts "https://github.com/elpiratilla/bus-tracker/blob/main/src/alerts.js"
click node_lead_form "https://github.com/elpiratilla/bus-tracker/blob/main/public/js/landing.js"
click node_school_tracking "https://github.com/elpiratilla/bus-tracker/blob/main/public/js/mapa.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_map_ui,node_fleet_ui,node_login_ui,node_web_push,node_lead_form,node_school_tracking toneBlue
class node_server,node_telemetry_api,node_routes_api,node_alerts_api,node_company_api,node_clients_api,node_driver_api,node_auth,node_company_auth toneAmber
class node_eta,node_tracking_logic,node_route_shapes,node_geo,node_state,node_database,node_alerts toneMint
class node_sensor,node_driver_app toneRose
class node_passenger,node_fleet_owner,node_family,node_driver toneIndigo
```

## Components

### User experiences

- [Live map](https://github.com/elpiratilla/bus-tracker/blob/main/public/js/mapa.js): `public/js/mapa.js`
- [Fleet panel](https://github.com/elpiratilla/bus-tracker/blob/main/public/js/panel.js): `public/js/panel.js`
- [Company access](https://github.com/elpiratilla/bus-tracker/blob/main/public/js/acceso.js): `public/js/acceso.js`
- [Push worker](https://github.com/elpiratilla/bus-tracker/blob/main/public/sw.js): `public/sw.js`
- [Sensor inquiry](https://github.com/elpiratilla/bus-tracker/blob/main/public/js/landing.js): `public/js/landing.js`
- [Private school tracking](https://github.com/elpiratilla/bus-tracker/blob/main/public/js/mapa.js): `public/js/mapa.js`

### Server API

- [Express server](https://github.com/elpiratilla/bus-tracker/blob/main/src/server.js): `src/server.js`
- [Telemetry API](https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/telemetry.js): `src/routes/telemetry.js`
- [Routes API](https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/rutas.js): `src/routes/rutas.js`
- [Alerts API](https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/alertas.js): `src/routes/alertas.js`
- [Fleet API](https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/empresa.js): `src/routes/empresa.js`
- [Lead API](https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/clientes.js): `src/routes/clientes.js`
- [Driver API](https://github.com/elpiratilla/bus-tracker/blob/main/src/routes/motorista.js): `src/routes/motorista.js`
- [Sensor auth](https://github.com/elpiratilla/bus-tracker/blob/main/src/middleware/auth.js): `src/middleware/auth.js`
- [Company auth](https://github.com/elpiratilla/bus-tracker/blob/main/src/middleware/empresa.js): `src/middleware/empresa.js`

### Transit processing

- [ETA engine](https://github.com/elpiratilla/bus-tracker/blob/main/src/eta.js): `src/eta.js`
- [Trip tracking](https://github.com/elpiratilla/bus-tracker/blob/main/src/tracking.js): `src/tracking.js`
- [Route geometry](https://github.com/elpiratilla/bus-tracker/blob/main/src/trazos.js): `src/trazos.js`
- [Geo calculations](https://github.com/elpiratilla/bus-tracker/blob/main/src/geo.js): `src/geo.js`
- [Transit state](https://github.com/elpiratilla/bus-tracker/blob/main/src/store.js): `src/store.js`
- [Supabase](https://github.com/elpiratilla/bus-tracker/blob/main/src/db.js): `src/db.js`
- [Arrival alerts](https://github.com/elpiratilla/bus-tracker/blob/main/src/alerts.js): `src/alerts.js`

### Location sources

- [ESP32 sensor](https://github.com/elpiratilla/bus-tracker/tree/main/firmware/go503_sensor): `firmware/go503_sensor`
- [Driver app](https://github.com/elpiratilla/bus-tracker/blob/main/public/js/motorista.js): `public/js/motorista.js`

### Other components

- **Passenger**
- **Fleet owner**
- **Family**
- **Driver**

## Connections

- Passenger → Live map: views buses (evidence: `README.md`)
- Live map → Routes API: requests route status
- Routes API → ETA engine: calculates arrivals (evidence: `src/routes/rutas.js`)
- ETA engine → Transit state: reads transit state (evidence: `src/eta.js`)
- ETA engine → Geo calculations: measures distance (evidence: `src/eta.js`)
- Passenger → Push worker: receives arrival alerts (evidence: `README.md`)
- Push worker → Alerts API: subscribes
- Alerts API → Arrival alerts: manages alerts (evidence: `src/routes/alertas.js`)
- Arrival alerts → ETA engine: estimates arrivals (evidence: `src/alerts.js`)
- Arrival alerts → Transit state: reads alert state (evidence: `src/alerts.js`)
- Fleet owner → Company access: signs in (evidence: `README.md`)
- Fleet owner → Fleet panel: manages fleet (evidence: `README.md`)
- Fleet panel → Fleet API: manages units
- Fleet panel → Routes API: views route data
- Fleet API → Company auth: checks company session (evidence: `src/routes/empresa.js`)
- Fleet API → Route geometry: edits route shapes (evidence: `src/routes/empresa.js`)
- Fleet API → Supabase: reads and writes fleet data (evidence: `src/routes/empresa.js`)
- Driver → Driver app: starts bus tracking (evidence: `README.md`)
- Driver app → Driver API: reports trip
- ESP32 sensor → Telemetry API: sends bus data (evidence: `README.md`)
- Telemetry API → Sensor auth: checks sensor key (evidence: `src/routes/telemetry.js`)
- Telemetry API → Trip tracking: updates trip tracking (evidence: `src/routes/telemetry.js`)
- Driver API → Trip tracking: controls trips (evidence: `src/routes/motorista.js`)
- Trip tracking → Route geometry: records GPS traces (evidence: `src/tracking.js`)
- Trip tracking → Geo calculations: finds nearby stops (evidence: `src/tracking.js`)
- Trip tracking → Supabase: persists trip data (evidence: `src/tracking.js`)
- Trip tracking → Transit state: updates trip state (evidence: `src/tracking.js`)
- Express server → Telemetry API: mounts endpoint (evidence: `src/server.js`)
- Express server → Routes API: mounts endpoint (evidence: `src/server.js`)
- Express server → Alerts API: mounts endpoint (evidence: `src/server.js`)
- Express server → Fleet API: mounts endpoint (evidence: `src/server.js`)
- Express server → Lead API: mounts endpoint (evidence: `src/server.js`)
- Express server → Driver API: mounts endpoint (evidence: `src/server.js`)
- Express server → Supabase: loads saved state (evidence: `src/server.js`)
- Fleet owner → Sensor inquiry: requests sensor (evidence: `README.md`)
- Sensor inquiry → Lead API: submits inquiry
- Family → Private school tracking: views private location (evidence: `README.md`)
