How jsantiago318/mayaguez-onebusaway-implementation works
1. This repository is a deployment package for a transit information stack for Mayagüez, not a single application source tree. It bundles three distinct subsystems: OneBusAway (rider-facing transit API), TransitClock (realtime prediction and feed generation), and Traccar (GPS/AVL tracking backend).
2. The top-level architectural boundary is therefore system integration. OBA-v1 and TClock are maintained as prebuilt/runtime artifacts plus scripts/config, while Traccar is documented as an external service installed separately on the host.
3. OBA-v1 is a Java OneBusAway runtime. Its main executable artifact is oba.war, which is used both to build the OBA data bundle from GTFS and to run the HTTP API service on port 8080.
4. OBA’s bundle/ directory is the precomputed runtime datastore. It contains serialized transit graph and indexing artifacts such as stop/route Lucene indexes, calendar data, shape/geospatial data, block trip/layer indices, alerts, and narrative/provider metadata. This means OBA is serving from a preprocessed read-optimized dataset rather than querying GTFS directly at request time.
5. OBA’s input boundary is the static GTFS feed in gtfs.zip, plus realtime feeds provided by TransitClock. The README indicates OBA expects GTFS-realtime trip updates, vehicle positions, and optionally alerts via environment variables pointing to TransitClock endpoints or keys.
6. TransitClock is the realtime processing layer. It is structured around shell scripts in TClock/bin/ for tasks like GTFS import, AVL import, AVL processing, travel-time updates, table creation, API key management, and database connectivity. This indicates a batch/daemon style service with explicit import and processing stages.
7. TransitClock stores its operational state in PostgreSQL, configured by config/postgres_hibernate.cfg.xml and config/transitclock.properties. The presence of SQL/table generation scripts and multiple test config files shows that it owns its own persistent backend and supports several deployment/test configurations.
8. TransitClock’s inputs are a static GTFS feed and AVL/vehicle location data. The repository includes sample data files such as data/avl.csv and GTFS archives under data/ and gtfs/, suggesting that TransitClock ingests schedule data and then combines it with live vehicle telemetry to compute predictions and feed outputs.
9. Traccar is the GPS tracking source system. In the documented deployment, it runs with MySQL as its persistence layer and is configured separately under /opt/traccar. TransitClock points at Traccar via TRACCAR_IP, TRACCAR_URL, credentials, and related config values, so Traccar is the upstream provider of raw AVL/location data.
10. The main data flow is: GTFS static schedule data enters TransitClock and OBA; Traccar produces live vehicle/location data; TransitClock processes those feeds into realtime trip updates, vehicle positions, and possibly alerts; OBA consumes those realtime feeds to answer rider-facing API queries. Apache/SSL and DigitalOcean are deployment infrastructure around the stack, not core application components.
11. The Dockerfiles and shell scripts are the operational glue. They define how each subsystem is built, started, and connected, but the repository itself is primarily an integration and installation bundle rather than a monolithic codebase.
Main entry points: oba.war OBA WAR · import_gtfs.sh Import stage · gtfs.zip GTFS feed · Dockerfile Docker glue
Components 18
Integration bundle
Repository-level deployment and wiring for the Mayagüez transit stack.
- Stack bundle · Repository that assembles OneBusAway, TransitClock, and Traccar into one deployment.
OneBusAway
Prebuilt rider-facing API runtime and precomputed transit bundle.
- OBA WAR · OneBusAway application package used to build and serve the rider API.
OBA-v1/oba.war - Transit graph · Precomputed transit graph and service data loaded by OneBusAway.
OBA-v1/bundle/TransitGraph.obj - Stop index · Read-optimized stop search index used by the API.
OBA-v1/bundle/StopSearchIndex - Route index · Read-optimized route search index used by the API.
OBA-v1/bundle/RouteSearchIndex - Schedule data · Calendar, block, frequency, shape, narrative, and alert artifacts that support trip lookup and rendering.
OBA-v1/bundle/CalendarServiceData.obj - GTFS feed · Static schedule feed used to build the OneBusAway bundle and seed TransitClock imports.
OBA-v1/gtfs.zip
TransitClock
Realtime processing layer for GTFS and AVL data.
- TransitClock · Batch and daemon-style service that ingests schedule and AVL data, maintains state, and produces realtime outputs.
- Import stage · Scripts for importing GTFS and AVL inputs into TransitClock.
TClock/bin/import_gtfs.sh - Process stage · Scripts that process AVL, update travel times, and build derived realtime tables.
TClock/bin/process_avl.sh - Admin tools · Utilities for table creation, API keys, database checks, and configuration setup.
TClock/bin/create_tables.sh - Postgres config · Hibernate and property configuration for TransitClock's PostgreSQL backend.
TClock/config/postgres_hibernate.cfg.xml - AVL inputs · Sample and imported AVL/location data used to drive realtime predictions.
TClock/data/avl.csv - GTFS import set · GTFS archive used by TransitClock's import and processing pipeline.
TClock/gtfs/Rutas.Urbanas.zip - Realtime feeds · Trip updates, vehicle positions, and related realtime products consumed by OneBusAway.
Deployment
Container and host-side glue for assembling the stack.
- Docker glue · Container definitions and launch scripts that assemble and start the stack components.
OBA-v1/Dockerfile - Host wiring · Shell helpers for startup, database connectivity, and runtime setup on the host.
TClock/go.sh
Other components
- Traccar · Separate GPS/AVL tracking backend installed and operated outside this repository.
Connections 20
- Stack bundle → OBA WAR: packages · The repository ships the OneBusAway runtime artifact.
- Stack bundle → TransitClock: includes · TransitClock is bundled as a separate runtime subsystem.
- Stack bundle → Traccar: integrates with · Traccar is documented as an external upstream service.
- GTFS feed → Transit graph: builds · Static GTFS is used to precompute the OneBusAway bundle.
- Transit graph → OBA WAR: served by · The WAR serves requests from the precomputed bundle.
- Stop index → OBA WAR: queried by · Stop lookup uses the prebuilt search index.
- Route index → OBA WAR: queried by · Route lookup uses the prebuilt search index.
- Schedule data → OBA WAR: supports · Calendar, shapes, and alerts enrich API responses.
- GTFS feed → Import stage: feeds · TransitClock imports the static schedule feed.
- AVL inputs → Process stage: drives · AVL data is processed into predictions and derived state.
- Traccar → AVL inputs: provides · Traccar is the upstream source for live vehicle/location data.
- GTFS import set → Import stage: feeds · TransitClock also imports schedule data from its own GTFS archive.
- Import stage → TransitClock: loads · Import scripts populate TransitClock's operational backend.
- Process stage → TransitClock: updates · Processing scripts maintain predictions and travel-time state.
- Postgres config → TransitClock: persists · TransitClock stores operational state in PostgreSQL.
- TransitClock → Realtime feeds: produces · TransitClock emits realtime transit feeds and updates.
- Realtime feeds → OBA WAR: consumed by · OneBusAway consumes realtime feeds for rider-facing queries.
- Docker glue → OBA WAR: starts · Container definitions help build and launch OneBusAway.
- Docker glue → TransitClock: starts · Container definitions help build and launch TransitClock.
- Host wiring → TransitClock: configures · Host scripts wire connectivity, startup, and deployment settings.