System Design Specification - WheresMyBus/android GitHub Wiki
Becky Leslie (beleslie) Bryce Martz (bmartz) Daniel Houtsma (dhoutsma) David Li (lidav6) Dylan Whitlow (whitldy) Nick Bissiri (nbissir)
Table of Contents
- System Architecture
- Diagrams
- Design Patterns
- Process
- Project Schedule
- Team Structure
- Test Plan
- Documentation Plan
- Coding Style Guidelines
- Design Changes and Rationale
#System Architecture
At the highest level the modules are: the database storing user-submitted alerts, the Rails server fetching information from the database and OneBusAway’s public API, and the Android user application. We also use the GoogleMapsAPI in the frontend of our app to display the map, labeling bus stops and bus locations.
The user app will submit requests to the server over HTTP, providing url parameters parsed by the Rails server. The server then inputs a query on the database and returns the result to the controller. For example, the controllers in the app will request bus route data to display a list of routes to the user. The server will respond to HTTP requests with JSON generated by Rails from the relevant objects, sending the JSON back to the controller. The user app will parse the JSON and build its own objects. Alerts will be formatted in the database as generated automatically in Rails from alert objects. Our plan to deal with any form of spam/false alerts is to simply use the upvoting and downvoting feature on an alert. We will also store the user id of the alert creator in the database, so we can detect users that have posted many alerts that have been heavily downvoted.
In our frontend, we will have several views:
- Map Screen
- Home Screen
- Alert Display Screen
- Alert Create Screen
- Catalog Screen
For non-alerts, almost all data will come from OneBusAway’s public API, which will be accessed for any request from a front end user. We considered a design in which the front end application would directly request this information from OneBusAway’s API, but decided that it would be simpler for our front end to only interact with our back end. We also considered a design in which data from OneBusAway would be stored by the server and periodically refreshed. We felt that we would want to update this data so frequently that storing it all would be redundant.
There are several kinds of data: alerts, busses, bus routes, bus stops, and neighborhoods. Each bus route contains multiple bus stops, and each bus corresponds to some route. Busses and stops have location coordinates used for display on a map. Alerts contain coordinates, text, date/time, duration, route, score, and bus ID. Neighborhoods are regions of 2D space used in the user app select a subset of all alerts, routes, stops and busses for display. For neighborhoods, we are currently supporting neighborhoods in Seattle defined here: http://seattle.findwell.com/seattle-neighborhoods/. We decided not to allow user defined neighborhoods, because we would like that if an alert was posted in Fremont, for example, the boundaries of Fremont would be constant for all users.
Our database schemas are as follows:
- Comments(string type, int commentId, string creatorId, string data, date created, date updated)
- Neighborhoods(string name, date created, date updated)
- NeighborhoodAlerts(string userId, string type, string description, int neighborhoodId, date created, date updated)
- RouteAlerts(string userId, string type, string description, string routeId, date created, date updated)
- Votes(string type, int voteId, string userId, int value, date created, date updated)
#Diagrams What follows are several diagrams demonstrating the system architecture.
##UML Class Diagram
Larger Version: http://imgur.com/A7jn6N5.png
In our diagram, the lines between views and controllers represent the fact that the views will have an instance of the controller and use the controller to request data from our server. See Design Patterns for distinctions between frontend/backend.
##System Architecture Diagram
In this diagram, the local storage in the app will store the information it receives from the server about bus stops, routes, and alerts.
##UML Sequence Diagrams
##Design Patterns: Our design above uses the following software design patterns: We are using a Model-View-Controller design strategy to build our app as a whole. - See UML Class Diagram: - View: AlertDisplay, AlertCreate, HomeScreen, MapScreen, CatalogScreen - Controllers: OBAController, WMBController - Model: Bus, BusStop, Alert, Route, Neighborhood, RouteAlert, NeighborhoodAlert, Comment
We will use the Singleton design for both our controllers, as it would not make sense to make multiple. See source code: OBAController.java, WMDController.java
Many of the classes of our Model are Wrappers, most notably a Route, which just wraps an int and String. See source code: Route.java, Comment.java
#Process
##Risk Assessment One of the main risks that may prevent us from building a functional app is being able to test it in the real world. Since we are including all the bus routes in King County, our app has a fairly large scope. This will make it difficult to simulate how it will actually be used by real people. It seems fairly likely that we will encounter this risk in our project. Fortunately though, it's impact will be relatively low because as long as the rest of our system is tested and working, there probably won't be that many scenarios that require large scale, real life testing. We have come to these conclusions based on the fact that there are dozens of bus routes in Seattle, each with multiple buses and a large amount of bus stops. So In order to address this problem, we figured we could either recruit a lot of people to actually go out and use our app, or just simulate the data instead.
In addition to providing a forum for alerts about specific bus routes, we wanted to implement the same kind of forum for neighborhood alerts, where people could submit information about situations like construction that would affect all the routes in part of a given neighborhood. This feature poses the risk, though, of distinguishing neighborhoods. The location data to distinguish the perimeter of every neighborhood, even in Seattle alone, would consume a large amount of storage. Furthermore, outside of the city, the distinction between different neighborhoods within a town might be more ambiguous. Since neighborhoods are defined by uneven borders, the risk of the location data for each perimeter requiring a lot of storage space has a high likelihood of occurring. If our servers cannot store the data for each neighborhood in King County or even Seattle, the risk would have a medium impact on our project because we would not be able to implement the forum for neighborhood alerts, one of our main features described in the SRS. Seattle alone has 127 neighborhoods, each of which likely have a pretty complex boundary that would require a lot of data to encode. To reduce the impact of this risk, we have been researching ways to get this information from a different source so we don't have to store it ourselves. We can detect the problem by attempting to store the data ourselves and see if it is too large for our database. If this risk does end up happening, we will instead implement a feature to find alerts near the user. Although it wouldn't be as granular, it would still provide the user with similar functionality.
Another risk we could potentially face is not finding out the optimal time for destroying our alerts. On one hand, if we keep the data for too long, it could be confusing to the user as they will see alerts for issues that have already been resolved. On the other hand, if we destroy it too early, we prevent the user from getting the information they're looking for. The chances of this problem occurring are relatively high. Different types of alerts will likely need to be active for different amounts of time and so it's hard to determine the optimal duration for all of them. This would have a medium impact as it could inconvenience the user a little bit, but it won't prevent the core features from working. Our estimates are based on the discussions we've had about the various types of issues that can affect busses and how long they would typically last. To reduce the likelihood of this risk, we'll do some research on the web for common problems that impact busses and how long they would be affected. We would also probably err on the side of caution and keep the alerts around for a little longer than we think because having the alert there and not needing it is better than needing an alert and it not being there. To see if this is actually a problem, we can check if users are complaining about whether alerts are lasting too long or not. For our mitigation plan, we could change our implementation to allow users to manually resolve alerts if they think the issue isn't applicable any more.
One last risk would be not getting enough alerts from the users. Our service will rely extensively on crowd sourced alerts and if people aren’t posting enough of them, others won’t want to use our app because of that. This risk probably has a higher chance of occurring because we don’t have a budget for marketing and we will likely rely on word of mouth to get people to use it. And if this risk were to happen, it would have a very high impact, because without any users posting alerts, our app won’t be as useful as we intended. Our estimates for this risk come from the realization that we need a decent amount of people using the app to make it fully functional. To reduce both the likelihood and the impact of this risk, we will utilize other sources of alerts, from transit agencies for instance, so we are still able to provide value to our users. We can detect if there are any problems by monitoring usage statistics such as number of active users or alert postings. In the case where this risk does occur, we can attempt to market it on social media and other platforms in order to get some traction and then hopefully there will be enough people submitting alerts to draws other people in too.
#Project Schedule ###Tasks for System Requirements Specification
| Tasks to Achieve the Milestone | Person/People who Completed the task | Length of Effort |
|---|---|---|
| Identify the major features of our app | Everyone | 9/29-9/30, 10/11 |
| Design UI diagrams | Daniel | 9/29-9/30, 10/14 |
| Write product description | Becky | 10/12-10/14 |
| Write process description | Dylan, Nick | 10/13-10/14 |
| Develop use cases | Bryce, David | 10/11-10/13 |
| Decide what software tools we will use | Everyone | 10/11 |
| Pinpoint the major risks | Everyone | 9/29-9/30, 10/14 |
| Create website, GitHub repo, and mailing list | Daniel | 10/12 |
###Tasks for System Design Specification
| Tasks to Achieve the Milestone | Person/People who Completed the task | Length of Effort |
|---|---|---|
| Define the system architecture | Everyone (Nick and Dylan documented) | 10/18-10/20 |
| Assess and develop plans to mitigate the major risks | Everyone (Becky documented) | 10/18-10/21 |
| Determine a plan for testing | Dylan, Nick | 10/18-10/20 |
| Formulate presentation | Bryce, Daniel, Nick | 10/21 |
| Install the software tools we plan to use | Everyone | 10/23 |
| Draft a schedule | Becky | 10/21 |
| Create UML Class and sequence diagrams, and System Architecture Diagram | David, Bryce, Daniel | 10/18-10/20 |
###Tasks for Zero Feature Release
| Tasks to Achieve the Milestone | Person/People who Completed the task | Length of Effort |
|---|---|---|
| Create skeletal implementation of our code, including comments | Becky, Bryce, David | 10/21-10/28 |
| Determine build instructions | Nick | 10/21-10/28 |
| Write user documentation | Becky | 10/21-10/28 |
| Write the developer documentation | Bryce, David, Dylan | 10/21-10/28 |
| Build user website | Daniel | 10/21-10/28 |
| Write system/integration tests | Bryce, Dylan, Nick | 10/21-10/28 |
| Build home page for the app | Becky | 10/21-10/28 |
| Set up the Heroku server and Travis | Daniel, Dylan | 10/21-10/28 |
###Tasks for Beta Feature Release
| Tasks to Achieve the Milestone | Person/People who Completed the task | Length of Effort |
|---|---|---|
| Update SDS | Everyone | 11/4-11/11 |
| Build OBA API, WBM API, product site | Daniel | 10/28-11/4 |
| Setup splash screen | Daniel, Becky | 10/28-11/4 |
| Build main activity screen | Becky | 10/28-11/4 |
| Build catalog screen | Bryce | 10/28-11/4 |
| Implement data modules | David | 10/28-11/4 |
| Unit test data modules | Nick | 10/28-11/4 |
| Implement front-end network interface | Dylan | 10/28-11/4 |
| Unit test data modules | David | 11/4-11/11 |
| Build submit alert screen | Becky | 11/4-11/11 |
| Finish catalog screen | Bryce, Becky | 11/4-11/11 |
| Build alert forum screen | Bryce, Becky | 11/4-11/11 |
| Finish APIs, helping with front end | Daniel | 11/4-11/11 |
| Update build scripts and instructions | Nick | 11/4-11/11 |
###Tasks for Feature Complete Release
| Tasks to Achieve the Milestone | Person/People who Completed the task | Length of Effort |
|---|---|---|
| Build map screens | Becky, Daniel | 11/11-11/21 |
| Finish all screens | Becky, Bryce, Daniel | 11/11-11/21 |
| Add navigation menu | Bryce | 11/11-11/21 |
| Prepare BFR Demo | Becky, David, Dylan | 11/13-11/15 |
| Write system tests | Nick, Dylan | 11/11-11/21 |
| Finish front end modules | Becky, Bryce, Daniel, David, Dylan | 11/11-11/21 |
| Finish front end unit tests | David, Nick | 11/11-11/21 |
| Finish back-end unit tests | Nick, Daniel | 11/11-11/21 |
| Finish back-end modules | Daniel | 11/11-11/21 |
| Saving and restoring user data | Nick | 11/11-11/21 |
| Update SDS | David, Bryce | 11/21 |
| Document and improve test coverage | David | 11/11-11/21 |
###Tasks for Release Candidate
| Tasks to Achieve the Milestone | Person/People who Completed the task | Length of Effort |
|---|---|---|
| Code review | Daniel, David, Dylan, Nick | 11/18-12/2 |
| Fix Bugs | Becky, Daniel, Bryce, Nick | 11/18-12/2 |
| Eat food | Everyone | 11/24 |
| Run user tests | Bryce, David | 11/30-12/2 |
###Tasks for Final Release
| Tasks to Achieve the Milestone | Person/People who Completed the task | Length of Effort |
|---|---|---|
| Maintain SRS Schedule | Becky | 10/23-12/9 |
| Work on demo | Becky, Daniel, Nick | 12/6-12/9 |
| Write post-mortem document | Bryce, David, Dylan | 12/6 |
#Team Structure The project manager of our group is Becky, and she will have the responsibility of making sure we are on schedule. Additionally, she will split the tasks for each milestone among the members of our group. Design decisions will be made through group discussion and a voting process. If a vote results in a tie, we defer to the project manager who will then make the final decision. The front-end team will consist firstly of Becky and Bryce with assistance from Daniel and Nick. Daniel is the back-end team and will develop the API as well as the integration with OneBusAway. Finally, we will have a testing team with Nick, David, and Dylan performing the integration and unit tests. Our group has been meeting twice a week, from 8:30am to 10:30am on Tuesday and Thursday. We will also schedule meetings in addition to those times when necessary. Lastly, we have been using Discord for text and voice chat when working apart from each other.
#Test Plan Unit testing will be performed on each major class to verify conformity to specification. We will use a combination of black and white box testing. For each module black box tests can be written first by a team member not responsible for its implementation, then white box tests by the implementer. We will use Travis for continuous integration. Tests will run on Travis every time a push to the repository occurs.
For system tests we intend to use stubs and mocks to focus on interactions between the front end (the Android app) and the back end and between the back end and One Bus Away. These tests will be automated with Appium’s Java packages. Performance tests will check that our application meets the expectations set in our non-functional requirements (e.g. launch speed and time to display alerts after posting) and possibly include some reasonable stress testing. System tests will primarily be the responsibility of members of the testing subgroup described in the SRS, which includes members working on both the front and back ends.
Usability tests will be performed as the application becomes functional from the perspective of a user. Initially the testers will be only our group members, but as the app becomes more complete we will try to include outside users as well. At first these tests can be done on just our own infrastructure, but at some point we will need to ride buses or wait at stops to test some features. This will potentially be difficult because most of our group members do not have Android phones. Some of our group members use the bus system daily to commute to and from the university, so once we start usability testing it should be possible for us to do so almost daily.
For all of the basic functionality of our application we expect these tests to be adequate. However it will be almost impossible to test the entire application comprehensively in a real world scenario without a larger user base and well-timed failures of the bus system.
As bugs appear they will be added to Github by the team members who discover them. When they are discovered how to reproduce the bug and how its behavior differs from expectations should be logged. If the member suspected of writing the code causing the bug has difficulty fixing the bug, then they will request that another member look for the bug most likely from the testing subgroup.
#Documentation Plan In order to help users figure out how to use Where’s My Bus?, we will provide a help button on the navigation menu of the app. This button sends the user to the user documentation found on our website, where they can find information on how to use our app.
#Coding Style Guidelines Ruby: https://github.com/bbatsov/ruby-style-guide Java: https://google.github.io/styleguide/javaguide.html
There are a few options available to ensure that we follow these style guides. For Ruby there is RuboCop (https://github.com/bbatsov/rubocop). It is a command line program that checks the style of Ruby code based on the guide above. There are also RuboCop plugins available for various text editors and IDEs. Finally, to enforce coding style for Java, we can use the XML code style configuration file provided by Google, in Android Studio. It is likely that these tools do not completely enforce every rule in the above style guides, so additionally, we can review each other’s code to make sure it conforms to the relevant coding style guidelines.
#Design Changes and Rationale:
-
Added a Comment class to allow users to comment about alert and discuss.
-
Distinguished between RouteAlert and NeighborhoodAlert, which inherit from an abstract class Alert. This allows users to either submit an alert about one route in particular (flat tires, reroutes) or an alert about a region with many routes (construction, heavy traffic).
-
Changed Route to only contain the name, number, and id of the route. Information about the list of BusStops and Busses were redundant and could be gathered from other places.
-
Changed Neighborhood to be defined as a perimeter, a list of points, allowing for more precise information about neighborhood. However, we are not implementing this in beta.
-
Added RetroFitAPI to handle asynchronous callbacks to our server.
-
Added VoteConfirmation.java to ensure that the server responded properly
-
Changed Team Dynamics to put more people on the front end team. We realized when working on the BFR that the front end was going to require more work, especially because nobody in our group has much experience with Android Studio
-
Changed the schedule to reflect what we actually did during development of the ZFR and Beta releases.
-
Minor details to the AlertSequenceDiagram - updated method calls and class names
Changes in Feature Complete Release
-
Changes to Bus: removed id, Route because they were unnecessary. Changed coordinate pair to separate doubles for serialization. Added direction of which way the bus was running.
-
Changes to upvote(), downvote() in Alert and Comment to take a parameter Callback, and have it call the server to upvote the post server side. We decided on this because there was no point just upvoting on the user's side without changing anything on the server side.
-
Updated Class diagram with updated names of views
-
Changed the help button in the app to send the user to our user documentation, where instructions on how to use our app are already available. This is instead of the initial idea of including a FAQ section in our app, which would have contained the same information.
-
Removed a paragraph in the risk assessment concerning a stretch feature we have chosen not to implement (automatically generated alerts) because we are no longer implementing it.
Design Changes in Release Candidate
-
Added unvote() methods in Alert and Comment, allowing users to undo their vote by clicking on the thumbs up/down again.
-
Added and removed certain fields/methods from objects as some were unnecessary/necessary. Most notably, we removed perimeter from Neighborhood, because we decided not to implement this feature. See UML Class Diagram.