# jsantiago318/oba-v1 architecture

> Architecture diagram of the GitHub repository jsantiago318/oba-v1, 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/oba-v1
- Repository: https://github.com/jsantiago318/oba-v1

## Overview

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`](https://github.com/jsantiago318/oba-v1/tree/master/bundle) (Bundle), [`oba.war`](https://github.com/jsantiago318/oba-v1/blob/master/oba.war) (OBA server), [`save_oba_gtfs_uprm`](https://github.com/jsantiago318/oba-v1/tree/master/save_oba_gtfs_uprm) (Preprocess), [`bundle/org_onebusaway_transit_data.script`](https://github.com/jsantiago318/oba-v1/blob/master/bundle/org_onebusaway_transit_data.script) (Local store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External Inputs"]
  node_gtfs_zip["GTFS feed<br/>static feed<br/>[gtfs.zip]"]
  node_realtime_alerts["Alerts feed<br/>optional live feed"]
  node_realtime_trips["Trip updates<br/>optional live feed"]
  node_realtime_vehicles["Vehicle feed<br/>optional live feed"]
  node_api_consumers(("Clients<br/>api consumers"))
end

subgraph group_build["Offline Build"]
  node_offline_build["Preprocess<br/>build pipeline"]
end

subgraph group_runtime["OneBusAway Runtime"]
  node_oba_war["OBA server<br/>java webapp<br/>[oba.war]"]
  node_http_api(("HTTP API<br/>web API"))
end

subgraph group_artifacts["Bundle Artifacts"]
  node_bundle_dir[("Bundle")]
  node_transit_graph["Transit graph<br/>graph index<br/>[TransitGraph.obj]"]
  node_calendar_data["Calendars<br/>service calendar"]
  node_block_trip_idx["Trip index<br/>schedule index"]
  node_block_layover_idx["Layover index<br/>schedule index"]
  node_freq_block_idx["Frequency trips<br/>schedule index"]
  node_narrative_data["Narratives<br/>content index"]
  node_shape_index["Shape index<br/>spatial index"]
  node_route_search[("Route search<br/>search index")]
  node_stop_search[("Stop search<br/>search index")]
  node_local_store[("Local store<br/>embedded datastore")]
end

node_gtfs_zip -->|"input"| node_offline_build
node_offline_build -->|"writes"| node_bundle_dir
node_bundle_dir -->|"contains"| node_transit_graph
node_bundle_dir -->|"contains"| node_calendar_data
node_bundle_dir -->|"contains"| node_block_trip_idx
node_bundle_dir -->|"contains"| node_block_layover_idx
node_bundle_dir -->|"contains"| node_freq_block_idx
node_bundle_dir -->|"contains"| node_narrative_data
node_bundle_dir -->|"contains"| node_shape_index
node_bundle_dir -->|"contains"| node_route_search
node_bundle_dir -->|"contains"| node_stop_search
node_bundle_dir -->|"contains"| node_local_store
node_oba_war -->|"serves"| node_http_api
node_http_api -->|"responses"| node_api_consumers
node_oba_war -->|"loads"| node_bundle_dir
node_oba_war -.->|"optional"| node_realtime_alerts
node_oba_war -.->|"optional"| node_realtime_trips
node_oba_war -.->|"optional"| node_realtime_vehicles
node_oba_war -->|"persists"| node_local_store

click node_gtfs_zip "https://github.com/jsantiago318/oba-v1/blob/master/gtfs.zip"
click node_offline_build "https://github.com/jsantiago318/oba-v1/tree/master/save_oba_gtfs_uprm"
click node_bundle_dir "https://github.com/jsantiago318/oba-v1/tree/master/bundle"
click node_transit_graph "https://github.com/jsantiago318/oba-v1/blob/master/bundle/TransitGraph.obj"
click node_calendar_data "https://github.com/jsantiago318/oba-v1/blob/master/bundle/CalendarServiceData.obj"
click node_block_trip_idx "https://github.com/jsantiago318/oba-v1/blob/master/bundle/BlockTripIndices.obj"
click node_block_layover_idx "https://github.com/jsantiago318/oba-v1/blob/master/bundle/BlockLayoverIndices.obj"
click node_freq_block_idx "https://github.com/jsantiago318/oba-v1/blob/master/bundle/FrequencyBlockTripIndices.obj"
click node_narrative_data "https://github.com/jsantiago318/oba-v1/blob/master/bundle/NarrativeProvider.obj"
click node_shape_index "https://github.com/jsantiago318/oba-v1/blob/master/bundle/ShapeGeospatialIndexData.obj.gz"
click node_route_search "https://github.com/jsantiago318/oba-v1/tree/master/bundle/RouteSearchIndex"
click node_stop_search "https://github.com/jsantiago318/oba-v1/tree/master/bundle/StopSearchIndex"
click node_local_store "https://github.com/jsantiago318/oba-v1/blob/master/bundle/org_onebusaway_transit_data.script"
click node_oba_war "https://github.com/jsantiago318/oba-v1/blob/master/oba.war"

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_gtfs_zip,node_realtime_alerts,node_realtime_trips,node_realtime_vehicles,node_api_consumers toneBlue
class node_offline_build toneAmber
class node_oba_war,node_http_api toneMint
class node_bundle_dir,node_transit_graph,node_calendar_data,node_block_trip_idx,node_block_layover_idx,node_freq_block_idx,node_narrative_data,node_shape_index,node_route_search,node_stop_search,node_local_store toneRose
```

## Components

### External Inputs

Static feed and optional live sources consumed by the packaged transit server.

- [GTFS feed](https://github.com/jsantiago318/oba-v1/blob/master/gtfs.zip): static feed · Primary transit schedule input used to build the deployment bundle. · `gtfs.zip`
- **Alerts feed**: optional live feed · External GTFS Realtime alerts source configured at deployment time.
- **Trip updates**: optional live feed · External GTFS Realtime trip updates source configured at deployment time.
- **Vehicle feed**: optional live feed · External GTFS Realtime vehicle positions source configured at deployment time.
- **Clients**: api consumers · External applications or operators calling the transit API.

### Offline Build

Preprocessing that converts GTFS into runtime-ready bundle artifacts.

- [Preprocess](https://github.com/jsantiago318/oba-v1/tree/master/save_oba_gtfs_uprm): build pipeline · 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](https://github.com/jsantiago318/oba-v1/blob/master/oba.war): java webapp · Packaged OneBusAway runtime started with java -jar and serving HTTP on port 8080. · `oba.war`
- **HTTP API**: web API · OneBusAway where-style endpoints exposed to clients.

### Bundle Artifacts

Precomputed indexes and persistent on-disk runtime data.

- [Bundle](https://github.com/jsantiago318/oba-v1/tree/master/bundle): artifact bundle · Precomputed runtime data directory loaded by the server. · `bundle`
- [Transit graph](https://github.com/jsantiago318/oba-v1/blob/master/bundle/TransitGraph.obj): graph index · Serialized transit network structure used for routing and coverage queries. · `bundle/TransitGraph.obj`
- [Calendars](https://github.com/jsantiago318/oba-v1/blob/master/bundle/CalendarServiceData.obj): service calendar · Operating dates and service availability data. · `bundle/CalendarServiceData.obj`
- [Trip index](https://github.com/jsantiago318/oba-v1/blob/master/bundle/BlockTripIndices.obj): schedule index · Trip-to-block scheduling index for service lookup and sequence traversal. · `bundle/BlockTripIndices.obj`
- [Layover index](https://github.com/jsantiago318/oba-v1/blob/master/bundle/BlockLayoverIndices.obj): schedule index · Layover timing index used by the runtime model. · `bundle/BlockLayoverIndices.obj`
- [Frequency trips](https://github.com/jsantiago318/oba-v1/blob/master/bundle/FrequencyBlockTripIndices.obj): schedule index · Index for frequency-based blocks and repeated service patterns. · `bundle/FrequencyBlockTripIndices.obj`
- [Narratives](https://github.com/jsantiago318/oba-v1/blob/master/bundle/NarrativeProvider.obj): content index · Route and stop narrative data for user-facing API responses. · `bundle/NarrativeProvider.obj`
- [Shape index](https://github.com/jsantiago318/oba-v1/blob/master/bundle/ShapeGeospatialIndexData.obj.gz): spatial index · Geospatial index for route shapes and geometry-backed lookups. · `bundle/ShapeGeospatialIndexData.obj.gz`
- [Route search](https://github.com/jsantiago318/oba-v1/tree/master/bundle/RouteSearchIndex): search index · Lucene-style route lookup index. · `bundle/RouteSearchIndex`
- [Stop search](https://github.com/jsantiago318/oba-v1/tree/master/bundle/StopSearchIndex): search index · Lucene-style stop lookup index. · `bundle/StopSearchIndex`
- [Local store](https://github.com/jsantiago318/oba-v1/blob/master/bundle/org_onebusaway_transit_data.script): embedded datastore · On-disk runtime state and logs used by the OneBusAway deployment. · `bundle/org_onebusaway_transit_data.script`

## Connections

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