Clarify local development in README

1 files changed, 42 insertions, 30 deletions

diff --git a/README.md b/README.md
index b661314b..d38f998e 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,44 @@ The OpenDC web server is the bridge between OpenDC's frontend and database. It i
 
 This document describes how to set up the web server for local development, and explains a high-level view of the web server architecture.
 
-## Setup
+## Architecture
+
+
+The following diagram shows a high-level view of the architecture of the OpenDC web server. Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow.
+
+![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png)
+
+The OpenDC API is implemented by the `Main Server Loop`, which is the only component in the base package.
+
+### Util Package
+
+The `Util` package handles several miscellaneous tasks:
+
+* `REST`: Parses SockerIO messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`.
+* `Param Checker`: Recursively checks whether required `Request` parameters are present and correctly typed.
+* `Exceptions`: Holds definitions for exceptions used throughough the web server.
+* `Database API`: Wraps SQLite functionality used by `Models` to read themselves from/ write themselves into the database.
+
+### API Package
+
+The `API` package contains the logic for the HTTP methods in each API endpoint. Packages are structured to mirror the API: the code for the endpoint `GET simulations/authorizations`, for example, would be located at the `Endpoint` inside the `authorizations` package, inside the `simulations` package (so at `api/simulations/authorizations/endpoint.py`).
+
+An `Endpoint` contains methods for each HTTP method it supports, which takes a request as input (such as `def GET(request):`). Typically, such a method checks whether the parameters were passed correctly (using the `Param Checker`); fetches some model from the database; checks whether the data exists and is accessible by the user who made the request; possibly modifies this data and writes it back to the database; and returns a JSON representation of the model.
+
+The `REST` component dynamically imports the appropriate method from the appropriate `Endpoint`, according to request it receives, and executes it.
+
+### Models Package
+
+The `Models` package contains the logic for mapping Python objects to their database representations. This involves an abstract `model` which has methods to `read`, `insert`, `update` and `delete` objects. Extensions of `model`, such as a `User` or `Simulation`, specify some metadata such as their tabular representation in the database and how they map to a JSON object, which the code in `model` uses in the database interaction methods.
+
+`Endpoint`s import these `Models` and use them to execute requests.
+
+## Setup for Local Development
 
 The following steps will guide you through setting up the OpenDC web server locally for development. To test individual endpoints, edit `static/index.html`. This guide was tested and developed on Windows 10.
 
+### Local Setup
+
 Make sure you have Python 2.7 installed (if not, get it [here](https://www.python.org/)), as well as pip (if not, get it [here](https://pip.pypa.io/en/stable/installing/)). Then run the following to install the requirements.
 
 ```bash
@@ -50,39 +84,17 @@ Make the following replacements:
 
 In `opendc-web-server/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=""`.
 
+### Local Development
+
 Run the server.
 
 ```bash
-python opendc-web-server/main.py config.json
+cd opendc-web-server
+python main.py config.json
 ```
 
-## Architecture
-
-The following diagram shows a high-level view of the architecture of the OpenDC web server. Squared-off colored boxes indicate packages (colors become more saturated as packages are nested); rounded-off boxes indicate individual components; dotted lines indicate control flow; and solid lines indicate data flow.
-
-![OpenDC Web Server Component Diagram](https://raw.githubusercontent.com/atlarge-research/opendc-web-server/master/images/opendc-web-server-component-diagram.png)
-
-The OpenDC API is implemented by the `Main Server Loop`, which is the only component in the base package.
-
-### Util Package
+Navigate to `http://localhost:8081/web-server-test` in a web browser (Chrome recommended), and open the console to see the server's response to the query in `static/index.html`.
 
-The `Util` package handles several miscellaneous tasks:
+To try a different query, edit the `path`, `method`, and/or `parameters` in `static/index.html`.
 
-* `REST`: Parses SockerIO messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`.
-* `Param Checker`: Recursively checks whether required `Request` parameters are present and correctly typed.
-* `Exceptions`: Holds definitions for exceptions used throughough the web server.
-* `Database API`: Wraps SQLite functionality used by `Models` to read themselves from/ write themselves into the database.
-
-### API Package
-
-The `API` package contains the logic for the HTTP methods in each API endpoint. Packages are structured to mirror the API: the code for the endpoint `GET simulations/authorizations`, for example, would be located at the `Endpoint` inside the `authorizations` package, inside the `simulations` package (so at `api/simulations/authorizations/endpoint.py`).
-
-An `Endpoint` contains methods for each HTTP method it supports, which takes a request as input (such as `def GET(request):`). Typically, such a method checks whether the parameters were passed correctly (using the `Param Checker`); fetches some model from the database; checks whether the data exists and is accessible by the user who made the request; possibly modifies this data and writes it back to the database; and returns a JSON representation of the model.
-
-The `REST` component dynamically imports the appropriate method from the appropriate `Endpoint`, according to request it receives, and executes it.
-
-### Models Package
-
-The `Models` package contains the logic for mapping Python objects to their database representations. This involves an abstract `model` which has methods to `read`, `insert`, `update` and `delete` objects. Extensions of `model`, such as a `User` or `Simulation`, specify some metadata such as their tabular representation in the database and how they map to a JSON object, which the code in `model` uses in the database interaction methods.
-
-`Endpoint`s import these `Models` and use them to execute requests.
+When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py config.json` in the console running the server) to see the result of your changes.