# jsantiago318/mayaguez-onebusaway-implementation architecture

> Architecture diagram of the GitHub repository jsantiago318/mayaguez-onebusaway-implementation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jsantiago318/mayaguez-onebusaway-implementation
- Repository: https://github.com/jsantiago318/mayaguez-onebusaway-implementation

## Overview

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-v1/oba.war`](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/oba.war) (OBA WAR), [`TClock/bin/import_gtfs.sh`](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/bin/import_gtfs.sh) (Import stage), [`OBA-v1/gtfs.zip`](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/gtfs.zip) (GTFS feed), [`OBA-v1/Dockerfile`](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/tree/main/OBA-v1/Dockerfile) (Docker glue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bundle["Integration bundle"]
  node_root["Stack bundle<br/>integration package"]
end

subgraph group_oba["OneBusAway"]
  node_oba_war["OBA WAR<br/>java runtime artifact<br/>[oba.war]"]
  node_oba_graph[("Transit graph<br/>serialized graph store<br/>[TransitGraph.obj]")]
  node_oba_stop_index[("Stop index<br/>lucene index")]
  node_oba_route_index[("Route index<br/>lucene index")]
  node_oba_schedule[("Schedule data<br/>bundle data")]
  node_oba_gtfs["GTFS feed<br/>static schedule input<br/>[gtfs.zip]"]
end

subgraph group_tclock["TransitClock"]
  node_tclock_core["TransitClock<br/>realtime processor"]
  node_tclock_import["Import stage<br/>ingest scripts<br/>[import_gtfs.sh]"]
  node_tclock_process["Process stage<br/>pipeline scripts<br/>[process_avl.sh]"]
  node_tclock_admin["Admin tools<br/>ops scripts<br/>[create_tables.sh]"]
  node_tclock_db["Postgres config<br/>database config"]
  node_tclock_inputs["AVL inputs<br/>vehicle telemetry input<br/>[avl.csv]"]
  node_tclock_gtfs["GTFS import set<br/>schedule input<br/>[Rutas.Urbanas.zip]"]
  node_tclock_outputs["Realtime feeds<br/>GTFS-RT output"]
end

subgraph group_deploy["Deployment"]
  node_docker_glue["Docker glue<br/>deployment scripts"]
  node_host_glue["Host wiring<br/>ops scripts<br/>[go.sh]"]
end

node_traccar["Traccar<br/>external gps service"]

node_root -->|"packages"| node_oba_war
node_root -->|"includes"| node_tclock_core
node_root -.->|"integrates with"| node_traccar
node_oba_gtfs -->|"builds"| node_oba_graph
node_oba_graph -->|"served by"| node_oba_war
node_oba_stop_index -->|"queried by"| node_oba_war
node_oba_route_index -->|"queried by"| node_oba_war
node_oba_schedule -->|"supports"| node_oba_war
node_oba_gtfs -->|"feeds"| node_tclock_import
node_tclock_inputs -->|"drives"| node_tclock_process
node_traccar -->|"provides"| node_tclock_inputs
node_tclock_gtfs -->|"feeds"| node_tclock_import
node_tclock_import -->|"loads"| node_tclock_core
node_tclock_process -->|"updates"| node_tclock_core
node_tclock_db -->|"persists"| node_tclock_core
node_tclock_core -->|"produces"| node_tclock_outputs
node_tclock_outputs -->|"consumed by"| node_oba_war
node_docker_glue -->|"starts"| node_oba_war
node_docker_glue -->|"starts"| node_tclock_core
node_host_glue -->|"configures"| node_tclock_core

click node_oba_war "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/oba.war"
click node_oba_graph "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/bundle/TransitGraph.obj"
click node_oba_stop_index "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/tree/main/OBA-v1/bundle/StopSearchIndex"
click node_oba_route_index "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/tree/main/OBA-v1/bundle/RouteSearchIndex"
click node_oba_schedule "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/bundle/CalendarServiceData.obj"
click node_oba_gtfs "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/gtfs.zip"
click node_tclock_import "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/bin/import_gtfs.sh"
click node_tclock_process "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/bin/process_avl.sh"
click node_tclock_admin "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/bin/create_tables.sh"
click node_tclock_db "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/config/postgres_hibernate.cfg.xml"
click node_tclock_inputs "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/data/avl.csv"
click node_tclock_gtfs "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/gtfs/Rutas.Urbanas.zip"
click node_docker_glue "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/tree/main/OBA-v1/Dockerfile"
click node_host_glue "https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/go.sh"

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_root toneBlue
class node_oba_war,node_oba_graph,node_oba_stop_index,node_oba_route_index,node_oba_schedule,node_oba_gtfs toneAmber
class node_tclock_core,node_tclock_import,node_tclock_process,node_tclock_admin,node_tclock_db,node_tclock_inputs,node_tclock_gtfs,node_tclock_outputs toneMint
class node_docker_glue,node_host_glue toneRose
class node_traccar toneNeutral
```

## Components

### Integration bundle

Repository-level deployment and wiring for the Mayagüez transit stack.

- **Stack bundle**: integration package · Repository that assembles OneBusAway, TransitClock, and Traccar into one deployment.

### OneBusAway

Prebuilt rider-facing API runtime and precomputed transit bundle.

- [OBA WAR](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/oba.war): java runtime artifact · OneBusAway application package used to build and serve the rider API. · `OBA-v1/oba.war`
- [Transit graph](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/bundle/TransitGraph.obj): serialized graph store · Precomputed transit graph and service data loaded by OneBusAway. · `OBA-v1/bundle/TransitGraph.obj`
- [Stop index](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/tree/main/OBA-v1/bundle/StopSearchIndex): lucene index · Read-optimized stop search index used by the API. · `OBA-v1/bundle/StopSearchIndex`
- [Route index](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/tree/main/OBA-v1/bundle/RouteSearchIndex): lucene index · Read-optimized route search index used by the API. · `OBA-v1/bundle/RouteSearchIndex`
- [Schedule data](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/bundle/CalendarServiceData.obj): bundle data · Calendar, block, frequency, shape, narrative, and alert artifacts that support trip lookup and rendering. · `OBA-v1/bundle/CalendarServiceData.obj`
- [GTFS feed](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/OBA-v1/gtfs.zip): static schedule input · 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**: realtime processor · Batch and daemon-style service that ingests schedule and AVL data, maintains state, and produces realtime outputs.
- [Import stage](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/bin/import_gtfs.sh): ingest scripts · Scripts for importing GTFS and AVL inputs into TransitClock. · `TClock/bin/import_gtfs.sh`
- [Process stage](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/bin/process_avl.sh): pipeline scripts · Scripts that process AVL, update travel times, and build derived realtime tables. · `TClock/bin/process_avl.sh`
- [Admin tools](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/bin/create_tables.sh): ops scripts · Utilities for table creation, API keys, database checks, and configuration setup. · `TClock/bin/create_tables.sh`
- [Postgres config](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/config/postgres_hibernate.cfg.xml): database config · Hibernate and property configuration for TransitClock's PostgreSQL backend. · `TClock/config/postgres_hibernate.cfg.xml`
- [AVL inputs](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/data/avl.csv): vehicle telemetry input · Sample and imported AVL/location data used to drive realtime predictions. · `TClock/data/avl.csv`
- [GTFS import set](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/gtfs/Rutas.Urbanas.zip): schedule input · GTFS archive used by TransitClock's import and processing pipeline. · `TClock/gtfs/Rutas.Urbanas.zip`
- **Realtime feeds**: GTFS-RT output · Trip updates, vehicle positions, and related realtime products consumed by OneBusAway.

### Deployment

Container and host-side glue for assembling the stack.

- [Docker glue](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/tree/main/OBA-v1/Dockerfile): deployment scripts · Container definitions and launch scripts that assemble and start the stack components. · `OBA-v1/Dockerfile`
- [Host wiring](https://github.com/jsantiago318/mayaguez-onebusaway-implementation/blob/main/TClock/go.sh): ops scripts · Shell helpers for startup, database connectivity, and runtime setup on the host. · `TClock/go.sh`

### Other components

- **Traccar**: external gps service · Separate GPS/AVL tracking backend installed and operated outside this repository.

## Connections

- 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.