Design Document
This document describes new software developed for the Onebusaway-NYC System. It provides design and architecture details of the system. It does not cover COTS (whether or not tailored and configured), or previously written and documented code.
This section describes architecture of the system.
The components outlined by the diagram above are described briefly below.
The queue server runs two ZeroMQ queues which are used to pass messages between components, as well as an HTTP proxy application. The bhs_queue contains "raw" (or relatively raw) Vehicle Location Messages as sent by the vehicles. It is populated by the HTTP proxy application. The hardware on each bus sends its messages to the HTTP proxy application, which delivers them onto the bhs_queue. Messages on this queue are consumed both by the inference engines and the report/archive server.
The inference output queue is populated with inferred location messages by the inference engine applications directly, and is read by the front-end CIS as well as the report/archive server.
The Inference Engine consumes raw bus messages and produces (for each reasonably valid raw message) an inferred message, which it sends to the inference output queue. An inferred message has been assigned to a block, run, phase, and trip, and has other attributes assigned as well, such as DSC, distance along trip/block, schedule deviation, etc.
There are multiple inference engines in the OBANYC infrastructure; currently two partitioned by depot map. They all consume messages from a single bhs_queue and write to a single output queue.
The Front-end CIS component consumes inferred messages, maintains current information on all known buses, and uses that information to answer queries from end users and render results, through various presentations. There are multiple instances of front-end CIS servers in the OBANYC infrastructure, but they have identical responsibilities (with a minor caveat noted below). The front-end CIS consists of several sub-components:
Transit Data Service is the component which consumes inferred messages, maintains current information on all known buses, and uses that information to answer queries from end users (via the presentation components).
This application provides desktop and mobile interfaces to NYC bus riders to track buses in real time. It serves as a primary interface through which users interact with the system. This is described in detail in User Interfaces section below.
The SMS web app handles and responds to incoming SMS requests (via Mobile Commons). At the moment, this is the one component of the front-end that is assigned to a specific server.
The API web app receives and responds to API requests from third-party applications.
Transit Data Manager contains configuration information for the entire system, and serves as a gateway between external data and the OBA system. This includes things like schedule data, service alerts, crew and depot information, etc. It also provides APIs to query vehicle data. Interface Design Document describes these APIs in detail
The Reporting and Archiving server consumes messages from both the raw and inferred queues and archives those messages to archive database. It provides APIs to query real time and historical data. These APIs are described in Interface Design Document.
Admin component provides web interfaces for performing administrative tasks such as transit bundle building, vehicle status tracking, user management etc. The application can be accessed only by "admin" users having valid credentials in the system.
This section describes detailed design of Onebusaway-NYC project.
At the core of the Bus CIS server project is a commitment to open standards. In general, this means:
- Transit Communications Interface Profiles (TCIP) XML or JSON,;
- Service Interface for Real Time Informaton (SIRI) XML; or
- well-documented JSON web services.
However, many of the Bus CIS Server services depend on other agencies/departments to provide data, which is often not in a standardized format. Bus CIS Server instead introduces conversion adapters to convert pre-formatted data into an open format.
Interface Design Document lists all the inbound and outbound interfaces to Onebusaway-NYC system. The detailed description of the interfaces are provided in the pages liked to this document.
JavaDoc for Onebusaway-NYC project can be found on http://developer.onebusaway.org/javadoc/modules/. Architecture section above gives high level overview of the various components of the system. The key services that comprise each component are described below.
Onebusaway-NYC system uses MySQL database hosted on Amazon's Relational Database Service (RDS) to persist data fetched from the queues. The database consists of a master database which supports both read and write operations as well as read replica which is kept in sync with the master. The read replica does not support write operation. There are two types of databases which differ in terms of information they store. These databases along with the tables are described in the Database Schema page.
Onebusaway-NYC System has two major types of users:
- a "general" user is a bus rider who uses the system for tracking buses in real time; and
- a "super" user such as admin or operator who has administrative privileges. This user works with "admin" section of the system for user management, bundle building, vehicle status etc.
This section describes each of these user interfaces with screen shots wherever appropriate.
The general user interfaces used by bus riders are described in detail in the General User Interface page.
The admin user interfaces used by admin users such as "admin" and "operator" are described in detail in the Admin User Interface page.
The inference engine contains some debug screens for developers and administrators. More detail is provided in the Debug User Interface page.