Prepare for release - README and LICENSE

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018 Gabriel Durazo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,13 +1,21 @@
-# Hawkeye - monitoring accuracy of GTFS RT predictions
+# Hawkeye - monitoring accuracy of MBTA GTFS RT predictions
 
-Needs a postgres database.
+Needs a postgres database. On macOS, [Postgres.app](https://postgresapp.com/) is a great way to install and use it. I also recommend [Postico](https://eggerapps.at/postico/) as a friendly GUI to explore the tables. You will need to create a DB for hawkeye, e.g. with the `createdb` command.
 
-Run with
+Build with `$ cargo build --release` or for macOS download a precompiled [release].
+
+Expects a `DATABASE_URL` that points to the postgres DB you set up for it.
+
+For example, if you've compiled the app yourself, run it with:
 
 ```
-$ env DATABASE_URL=postgres://user@localhost:5432/db_name cargo run --release
+$ env DATABASE_URL=postgres://user@localhost:5432/db_name target/release/hawkeye
 ```
 
+The app creates and maintains two tables: `vehicle_movements` and `predictions`.
+
 The `vehicle_movements` table records when a train arrives at and departs from a stop. This is inferred from the VehiclePositions.pb file, when the status goes to and from STOPPED_AT, so is correct to within the resolution of how often we fetch the file (currently about every 2 - 2.5 seconds).
 
 Note that there's no concept of trip in this table, sicne there's no concept of trip in VehiclePositions. That means, the max table size is (# of unique vehicle IDs) x (number of stops they can be at). If a vehicle visits a stop that it's been to in the past, the row in the DB will be updated.
+
+The `predictions` table stores the predictions made in the `TripUpdates.pb` file, which is downloaded once a minute. Every minute, we create a new record with `file_at` (the timestamp of when the PB file was downloaded), the `trip_id`, `vehicle_id`, `stop_id`, `stop_sequence`, and `predicted_arrive_at` and `predicted_depart_at`. Every couple seconds when the `vehicle_movements` table is updated, if a vehicle newly arrives at or departs from a stop, all of the predictions for that stop and vehicle have their `actual_arrive_at` and `actual_depart_at` timestamps updated.