From 1b49b7bbb20c2104b3aad339c427475486562953 Mon Sep 17 00:00:00 2001 From: barbeau Date: Wed, 1 Nov 2017 16:30:26 -0400 Subject: [PATCH] Fix #814 - Add system architecture documentation --- CUSTOM_SERVERS.md | 2 ++ README.md | 4 ++++ SYSTEM_ARCHITECTURE.md | 48 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+) create mode 100644 SYSTEM_ARCHITECTURE.md diff --git a/CUSTOM_SERVERS.md b/CUSTOM_SERVERS.md index a6d7c897a..362cd590c 100644 --- a/CUSTOM_SERVERS.md +++ b/CUSTOM_SERVERS.md @@ -2,6 +2,8 @@ We support testing custom [OneBusAway](https://github.com/OneBusAway/onebusaway-application-modules/wiki) and [OpenTripPlanner](http://www.opentripplanner.org/) servers in OneBusAway Android. You can use this feature to try out a new test server that you've set up, but aren't ready to publicize in the [Regions API](https://github.com/OneBusAway/onebusaway/wiki/Multi-Region) yet. + +Before doing anything, check out the [system architecture diagrams](SYSTEM_ARCHITECTURE.md) to understand how OBA Android communicates with other servers. and what features they provide. ## Configuration diff --git a/README.md b/README.md index ec0e75b84..b59740952 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,10 @@ Get early access to new OneBusAway Android versions, and help us squash bugs! Se Did you just set up your own [OneBusAway](https://github.com/OneBusAway/onebusaway-application-modules/wiki) and/or [OpenTripPlanner](http://www.opentripplanner.org/) server? You can test both in this app without compiling any Android code. Just download the app from [Google Play](https://play.google.com/store/apps/details?id=com.joulespersecond.seattlebusbot), and see our [Custom Server Setup Guide](CUSTOM_SERVERS.md) for details. +## System Architecture + +Curious what servers power certain features in OneBusAway Android? Check out the [System Architecture page](SYSTEM_ARCHITECTURE.md). + ## Build Setup We use [Gradle build flavors](http://developer.android.com/tools/building/configuring-gradle.html#workBuildVariants) to enable a number of different build variants of OneBusAway Android. diff --git a/SYSTEM_ARCHITECTURE.md b/SYSTEM_ARCHITECTURE.md new file mode 100644 index 000000000..04a4c4cc3 --- /dev/null +++ b/SYSTEM_ARCHITECTURE.md @@ -0,0 +1,48 @@ +# System architecture + +OneBusAway Android is a client application that requires real-time server access in order to provide information to users. + +OneBusAway uses a [multi-region architecture](https://github.com/OneBusAway/onebusaway/wiki/Multi-Region) where each region (e.g., Tampa, Seattle) is responsible for running their own open-source OneBusAway server (the [onebusaway-application-modules project](https://github.com/OneBusAway/onebusaway-application-modules)). + +The following sections present three different regional deployment architecture examples: +1. A simple deployment that uses only the OneBusAway server +2. A deployment that adds trip planning and bike share information +3. A deployment that adds issue reporting via an Open311 server + +Note that you can have all three of the above active at once - the Tampa Bay region currently uses all three. + +The below system architecture diagrams come from [this Google Drawing](https://docs.google.com/drawings/d/1Z4D8n1PPI7U-G1VgYxehsvyGeVBv6mveGTkgfSbKhCo/edit?usp=sharing). + +## Simple deployment + +The simplest way to get started is to deploy a OneBusAway server, which will give you estimated arrival times and server alerts in the app. Here's the basic system architecture diagram for this configuration: + +![onebusaway system architecture-basic](https://user-images.githubusercontent.com/928045/32296017-5dd339e4-bf21-11e7-962c-327cf071b5ba.png) + +## Add trip planning and/or bike share *(Optional)* + +If you want to add trip planning and/or bike share information, you'll need to set up an OpenTripPlanner server. See [this article](https://medium.com/@sjbarbeau/bike-share-launches-in-onebusaway-3452c08c0ed) for details about the bike share features. Here's the system architecture for a region that's added trip planning and bike share information (e.g., Tampa Bay): + +![onebusaway system architecture-otp](https://user-images.githubusercontent.com/928045/32296042-69aa4726-bf21-11e7-8123-1f80c17fee4c.png) + +## Add issue reporting via Open311-compliant system *(Optional)* + +If you use an issue management system that supports the Open311 standard, you can have OneBusAway Android submit problem reports to this system, including metadata from the stop/trip they are reporting the problem about as well as an attached picture. See [this presentation](https://www.slideshare.net/sjbarbeau/2017-seeclickfix-workshop-closing-the-loop-improving-transit-through-crowdsourced-information) for details about the enhanced issue reporting feature. Here's the system architecture for a region that's added issue reporting via Open311 (e.g., Tampa Bay): + +![onebusaway system architecture-open311](https://user-images.githubusercontent.com/928045/32296055-721a068a-bf21-11e7-922d-f167118d2390.png) + +## Configure your own servers + +#### OneBusAway and OpenTripPlanner + +See the [Getting Started](https://github.com/OneBusAway/onebusaway-application-modules#getting-started) section of the **onebusaway-application-modules** project to set up your own OneBusAway server - this is a good place to start, and will give you arrival estimates and service alerts in the OneBusAway Android app. + +After you have the OneBusAway server set up, see the [Custom Servers](CUSTOM_SERVERS.md) documentation in this project to see how you can test OneBusAway Android with your new OBA server. + +After you've tested arrival information, if you want to add trip planning and/or bike share information, see the [Basic Usage](http://docs.opentripplanner.org/en/latest/Basic-Usage/) documentation for setting up an OpenTripPlanner server. + +When you have this set up, see the [Custom Servers](CUSTOM_SERVERS.md) documentation again to point your OBA Android app to your new OTP server. + +#### Open311 + +Currently we don't have a way to easily plug an Open311 server URL directly into the OBA Android app UI to test, but [let us know](https://github.com/OneBusAway/onebusaway/wiki/Contact-Us) if you'd like to test it out and we'll help out. \ No newline at end of file