How jsantiago318/oba-v1 works
1. What this repository is
- This repo is not application source code; it is a packaged deployment of OneBusAway transit data server, customized for a specific city/agency dataset.
- The important architectural idea is that the system is split into a prebuilt runtime app (oba.war) and a precomputed data bundle (bundle/) generated from GTFS input.
2. Primary runtime component
- The main executable is oba.war, a Java web application.
- It is started directly with java -jar, and it serves HTTP on port 8080 inside the container.
- The app exposes OneBusAway “where” API endpoints, for example:
- /api/where/agencies-with-coverage.xml?key=TEST
3. Data ingestion and build-time preprocessing
- The build step takes gtfs.zip as the transit feed input and writes results into bundle/.
- This is an offline preprocessing pipeline, not a live ETL service: GTFS is converted into optimized serialized indexes and graph artifacts before the server runs.
- The README’s startup command shows the build contract clearly:
- input: gtfs.zip
- output: bundle/
4. Core data artifacts in bundle/
- bundle/ holds the server’s persistent transit model and search indexes.
- The files indicate several precomputed subsystems:
- TransitGraph.obj — transit network/graph structure
- CalendarServiceData.obj — service calendars and operating dates
- BlockTripIndices.obj, BlockLayoverIndices.obj, FrequencyBlockTripIndices.obj — trip/block scheduling indexes
- NarrativeProvider.obj — user-facing route/stop narrative data
- ShapeGeospatialIndexData.obj.gz — shape/geometry spatial index
- RouteSearchIndex/ and StopSearchIndex/ — Lucene-style search indexes for lookup
5. Serving model
- At runtime, the Java server loads the prebuilt bundle and uses it to answer API queries quickly.
- The architecture is therefore read-mostly and file-backed: most transit intelligence is materialized ahead of time, then read by the API server.
- This is why the repo ships large binary artifacts rather than source code.
6. External data dependencies
- gtfs.zip is the core static transit feed.
- The README also mentions optional city-specific GTFS Realtime URLs:
- gtfsRealtimeAlertsUrl
- gtfsRealtimeTripUpdatesUrl
- gtfsRealtimeVehiclePositionsUrl
- Those are external live data sources, but they are configuration inputs rather than code in this repo.
7. Containerization
- Dockerfile wraps the Java runtime and makes the service deployable as a single container.
- The Docker image exposes the app on port 8080 and is intended to be run as a single-instance service.
- The container boundary is simple: it contains the WAR, the bundle, and the GTFS-derived assets.
8. Operational flow
- The likely lifecycle is:
1. build or update transit data from gtfs.zip
2. generate/update bundle/
3. package or run oba.war
4. serve HTTP APIs from the precomputed transit model
- This means changes to transit data require rebuilding the bundle, not just restarting the service.
9. Persistence and local state
- The presence of files like org_onebusaway_transit_data.*, *.lck, and *.log suggests embedded local datastore/index state used by the OneBusAway runtime.
- These are operational artifacts, not source assets, and indicate the server maintains its own on-disk persistence/indexing layer alongside the bundle.
10. Deployment context
- The README notes DigitalOcean as the hosting platform.
- The intended deployment pattern is a basic cloud VM or container host running Docker, with optional HTTPS and scalability handled externally (for example via Apache, per the README).
11. Architectural boundary summary
- The key boundary to capture in a diagram is:
- Static transit data + GTFS preprocessing on one side
- Java API server using prebuilt indexes on the other
- There is no evidence of separate frontend, message queue, database service, or microservice mesh in this repo.
12. What to show in an architecture diagram
- Include these main nodes:
- GTFS feed (gtfs.zip)
- build/preprocess step
- bundle/index artifacts
- OneBusAway WAR runtime
- HTTP API consumers
- optional GTFS Realtime external feeds
- The main data flow is from GTFS into the bundle, then from bundle into the server, then out through HTTP responses.
Main entry points: bundle Bundle · oba.war OBA server · save_oba_gtfs_uprm Preprocess · org_onebusaway_transit_data.script Local store
Components 19
External Inputs
Static feed and optional live sources consumed by the packaged transit server.
- GTFS feed · Primary transit schedule input used to build the deployment bundle.
gtfs.zip - Alerts feed · External GTFS Realtime alerts source configured at deployment time.
- Trip updates · External GTFS Realtime trip updates source configured at deployment time.
- Vehicle feed · External GTFS Realtime vehicle positions source configured at deployment time.
- Clients · External applications or operators calling the transit API.
Offline Build
Preprocessing that converts GTFS into runtime-ready bundle artifacts.
- Preprocess · Offline conversion of GTFS into serialized transit model and search indexes.
save_oba_gtfs_uprm
OneBusAway Runtime
Packaged Java webapp that loads the bundle and serves transit APIs.
- OBA server · Packaged OneBusAway runtime started with java -jar and serving HTTP on port 8080.
oba.war - HTTP API · OneBusAway where-style endpoints exposed to clients.
Bundle Artifacts
Precomputed indexes and persistent on-disk runtime data.
- Bundle · Precomputed runtime data directory loaded by the server.
bundle - Transit graph · Serialized transit network structure used for routing and coverage queries.
bundle/TransitGraph.obj - Calendars · Operating dates and service availability data.
bundle/CalendarServiceData.obj - Trip index · Trip-to-block scheduling index for service lookup and sequence traversal.
bundle/BlockTripIndices.obj - Layover index · Layover timing index used by the runtime model.
bundle/BlockLayoverIndices.obj - Frequency trips · Index for frequency-based blocks and repeated service patterns.
bundle/FrequencyBlockTripIndices.obj - Narratives · Route and stop narrative data for user-facing API responses.
bundle/NarrativeProvider.obj - Shape index · Geospatial index for route shapes and geometry-backed lookups.
bundle/ShapeGeospatialIndexData.obj.gz - Route search · Lucene-style route lookup index.
bundle/RouteSearchIndex - Stop search · Lucene-style stop lookup index.
bundle/StopSearchIndex - Local store · On-disk runtime state and logs used by the OneBusAway deployment.
bundle/org_onebusaway_transit_data.script
Connections 19
- GTFS feed → Preprocess: input · GTFS feed is converted into runtime-ready assets.
- Preprocess → Bundle: writes · Build step materializes the bundle directory.
- Bundle → Transit graph: contains · Bundle stores the serialized transit graph.
- Bundle → Calendars: contains · Bundle stores calendar/service availability data.
- Bundle → Trip index: contains · Bundle stores trip block index artifacts.
- Bundle → Layover index: contains · Bundle stores layover scheduling artifacts.
- Bundle → Frequency trips: contains · Bundle stores frequency-based trip indices.
- Bundle → Narratives: contains · Bundle stores narrative content for API responses.
- Bundle → Shape index: contains · Bundle stores spatial shape indexing data.
- Bundle → Route search: contains · Bundle stores route lookup index files.
- Bundle → Stop search: contains · Bundle stores stop lookup index files.
- Bundle → Local store: contains · Bundle-side local datastore and persistent runtime state.
- OBA server → HTTP API: serves · Java webapp exposes the OneBusAway HTTP API.
- HTTP API → Clients: responses · Clients query the API and receive transit data responses.
- OBA server → Bundle: loads · Runtime reads precomputed bundle artifacts at startup and during queries.
- OBA server → Alerts feed: optional · Runtime may consume external realtime alerts if configured.
- OBA server → Trip updates: optional · Runtime may consume external trip updates if configured.
- OBA server → Vehicle feed: optional · Runtime may consume external vehicle positions if configured.
- OBA server → Local store: persists · Server maintains local on-disk state and indexes alongside the bundle.