Merge remote-tracking branch 'origin/dev-2.x' into flex

ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# OTP Architecture
+OTP is developed over more than 10 years, and most of the design documentation is in the code 
+as comments and JavaDoc. Over the years the complexity have increased, and the natural developer 
+turnover naturally creat a demand for more architecture and design documentation. The new OTP2 
+documentation is put together with the source; hopefully making it easier to maintain. Instead of
+documenting modules in old style _package-info.java_ files we use _package.md_ files. This document
+should serve as an index to all existing top-level documented components.
+
+This document is fare from complete - hopefully it can evolve over time and become a good 
+introduction to OTP architecture. The OTP project GitHub issues are a good place look for detailed 
+discussions on many design decisions.   
+
+Be sure also the read the [developer documentation](docs/Developers-Guide.md). 
+
+## Modules/Components
+Below is a list of documented components in OTP. Not every component is documented at a high level,
+but this is a start, and we would like to expand this list in the future.
+
+### [OTP Configuration design](src/main/java/org/opentripplanner/standalone/config/package.md)
+
+The Configuration module is responsible for loading and parsing OTP configuration files and map 
+them into POJOs. These POJOs are injected into the other components.
+
+
+### [REST API](src/main/java/org/opentripplanner/api/package.md)
+
+Short introduction to the REST API.
+
+
+### [GTFS import module](src/main/java/org/opentripplanner/gtfs/package.md)
+
+Used to import GTFS transit data files.
+
+
+### [Raptor transit routing](src/main/java/org/opentripplanner/transit/raptor/package.md)
+
+This is the OTP2 new transit routing engine implemented using the Raptor algorithm. It explains how
+Raptor works, the important concepts, and the design. It might be worth reading even if you are not
+a developer - just to understand how the transit routing works. 
+
+The Raptor functionality is quite complex, so we want to isolate the problem. Therefore, is the 
+raptor component designed to have as few dependencies as possible. In fact there is _no_ 
+dependencies from Raptor to other parts of OTP code, only to utility classes not found in the JDK.
+Also, the code follows a stricter object-oriented design, than most other parts of OTP. The Raptor 
+implementation is highly critical code, hence we set the bar higher with respect to code quality.
+
+OTP provide transit data to Raptor by implementing the _raptor/api/transit_ model. The 
+[RoutingService](src/main/java/org/opentripplanner/routing/RoutingService.java)
+is responsible for mapping from the OTP context to a 
+[RaptorRequest](src/main/java/org/opentripplanner/transit/raptor/api/request/RaptorRequest.java)
+and then map the result, [Raptor Path](src/main/java/org/opentripplanner/transit/raptor/api/path/Path.java),
+back to the OTP internal domain. This might seem like a lot of unnecessary mapping, but 
+mapping is simple - routing is not. 
+
+The performance of Raptor is important, and we care about every millisecond. All changes to the
+existing Raptor coded should be tested with the 
+[SpeedTest](src/test/java/org/opentripplanner/transit/raptor/speed_test/package.md) and 
+compared with an earlier version of the code to make sure the performance is NOT degraded. 

README.md

@@ -1,29 +1,27 @@
 ## Overview
 
-OpenTripPlanner (OTP) is an open source multi-modal trip planner. It depends on open data in open standard file formats (GTFS and OpenStreetMap), and includes a REST API for journey planning as well as a map-based Javascript client. OpenTripPlanner can also create travel time contour visualizations and compute accessibility indicators for planning and research applications. For more information, see the project website: http://opentripplanner.org
+OpenTripPlanner (OTP) is an open source multi-modal trip planner, focusing on travel by scheduled public transportation in combination with bicycling, walking, and mobility services including bike share and ride hailing. Its server component runs on any platform with a Java virtual machine (including Linux, Mac, and Windows). It exposes REST and GraphQL APIs that can be accessed by various clients including open source Javascript components and native mobile applications. It builds its representation of the transportation network from open data in open standard file formats (primarily GTFS and OpenStreetMap). It applies real-time updates and alerts with immediate visibility to clients, finding itineraries that account for disruptions and service changes.
 
-The main Java server code is in `src/main/`. OTP also includes a Javascript client based on the Leaflet mapping library in `src/client/`. The Maven build produces a JAR file at `target/otp-VERSION.jar` containing all necessary code and dependencies to run OpenTripPlanner.
+Note that this branch contains **OpenTripPlanner 2**, the second major version of OTP, which has been under development since Q2 2018 and is approaching release. As of September 2020, OTP2 is in feature freeze and we have tagged a release candidate `v2.0-RC1` which is undergoing testing. 
 
-Additional information and instructions are available in the [main documentation](http://docs.opentripplanner.org/en/latest/), including a 
-[quick introduction](http://docs.opentripplanner.org/en/latest/Basic-Tutorial/).
+If you do not want to test or explore this cutting edge version, please switch to the `master` or `dev-1.x` branches for the latest stable 1.x release and upcoming final 1.x release respectively.
 
-[![Build Status](https://travis-ci.org/opentripplanner/OpenTripPlanner.svg?branch=master)](https://travis-ci.org/opentripplanner/OpenTripPlanner)
+## Respository layout
+
+The main Java server code is in `src/main/`. OTP also includes a Javascript client based on the Leaflet mapping library in `src/client/`. This client is now primarily used for testing, with most major deployments building custom clients from reusable components. The Maven build produces a unified ("shaded") JAR file at `target/otp-VERSION.jar` containing all necessary code and dependencies to run OpenTripPlanner.
+
+Additional information and instructions are available in the [main documentation](http://docs.opentripplanner.org/en/dev-2.x/), including a 
+[quick introduction](http://docs.opentripplanner.org/en/dev-2.x/Basic-Tutorial/).
 
 ## Development 
 
 OpenTripPlanner is a collaborative project incorporating code, translation, and documentation from contributors around the world. We welcome new contributions. Further [development guidelines](http://docs.opentripplanner.org/en/latest/Developers-Guide/) can be found in the documentation.
 
 ### Development history
 
-The OpenTripPlanner project was launched by Portland, Oregon's transport agency TriMet (http://trimet.org/), and began in July of 2009 with a kick-off conference bringing together transit agencies and the authors of the major open source transit passenger information software of the day: David Emory of FivePoints, Brian Ferris of OneBusAway, and Brandon Martin-Anderson of GraphServer. From 2008 through 2012, development was coordinated by New York nonprofit OpenPlans (http://openplans.org/). By early 2013, OpenTripPlanner had become the primary trip planning software used by TriMet in the Portland regional trip planner (http://ride.trimet.org/) and was backing several popular mobile applications. Public-facing OpenTripPlanner instances were available in at least ten countries throughout the world. At this point the OpenPlans transportation software team became the independent consultancy Conveyal (http://www.conveyal.com/). The original OpenTripPlanner development team from OpenPlans still actively participates in programming, design, and community coordination via the mailing list and their roles on the OTP Project Leadership Committee.
-
-In summer of 2013, the OpenTripPlanner project was accepted for membership in the Software Freedom Conservancy (SFC). SFC handles the legal and financial details common to many open source projects, providing a formal framework for OTP and allowing contributors to concentrate on the code. For more information, see the SFC website at http://sfconservancy.org/.
-
-After seven years of hard work and almost 10,000 commits from over 100 contributors around the world, version 1.0 was released on 9 September 2016.
-
-TODO OTP2: Write a short sentence about the OTP2 work: Raptor, Ruter/Entur, NeTEx, GraphQL APIs.
+The OpenTripPlanner project was launched by Portland, Oregon's transport agency TriMet (http://trimet.org/) in July of 2009. As of this writing in Q3 2020, it has been in development for over ten years. See the main documentation for an overview of [OTP history](http://docs.opentripplanner.org/en/dev-2.x/History/) and a list of [cities and regions using OTP](http://docs.opentripplanner.org/en/dev-2.x/Deployments/) around the world.
 
 
 ## Mailing Lists
 
-The main forums through which the OpenTripPlanner community organizes development and provides mutual assistance are our two Google discussion groups. Changes and extensions to OTP are debated on the developers' list - [opentripplanner-dev](https://groups.google.com/forum/#!forum/opentripplanner-dev). More general questions and announcements of interest to non-developer OTP users should be directed to the [opentripplanner-users](https://groups.google.com/forum/#!forum/opentripplanner-users) list.
+The main forums through which the OpenTripPlanner community organizes development and provides mutual assistance are our two Google discussion groups. Changes and extensions to OTP are debated on the [opentripplanner-dev](https://groups.google.com/forum/#!forum/opentripplanner-dev) developers' list. More general questions and announcements of interest to non-developer OTP users should be directed to the [opentripplanner-users](https://groups.google.com/forum/#!forum/opentripplanner-users) list. Other details of [project governance](http://docs.opentripplanner.org/en/dev-2.x/Governance/) can be found in the main documentation.