Merge pull request #9 from atlarge-research/feat/opendc-node

Add simulator integration

1 files changed, 101 insertions, 0 deletions

diff --git a/api/README.md b/api/README.md
new file mode 100644
index 00000000..4e8110d0
--- /dev/null
+++ b/api/README.md
@@ -0,0 +1,101 @@
+<h1 align="center">
+    <img src="../misc/artwork/logo.png" width="100" alt="OpenDC">
+    <br>
+    OpenDC Web Server
+</h1>
+<p align="center">
+    Collaborative Datacenter Simulation and Exploration for Everybody
+</p>
+
+<br>
+
+The OpenDC web server is the bridge between OpenDC's frontend and database. It is built with Flask/SocketIO in Python and implements the OpenAPI-compliant [OpenDC API specification](../opendc-api-spec.yml).
+
+This document explains a high-level view of the web server architecture ([jump](#architecture)), and describes how to set up the web server for local development ([jump](#setup-for-local-development)).
+
+## 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](misc/artwork/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:
+
+* `Database API`: Wraps database access functionality used by `Models` to read themselves from/write themselves into the database.
+* `Exceptions`: Holds definitions for exceptions used throughout the web server.
+* `Parameter Checker`: Recursively checks whether required `Request` parameters are present and correctly typed.
+* `REST`: Parses SocketIO and HTTP messages into `Request` objects, and calls the appropriate `API` endpoint to get a `Response` object to return to the `Main Server Loop`.
+
+### 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 api/projects`, for example, would be located at the `endpoint.py` inside the `projects` package (so at `api/projects/endpoint.py`).
+
+An `endpoint.py` file 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 `Parameter 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 generic CRUD operations. Extensions of `model`, such as a `User` or `Project`, specify some more specific operations and their collection metadata.
+
+`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`.
+
+### Local Setup
+
+#### Install requirements
+
+Make sure you have Python 3.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
+pip install -r requirements.txt
+```
+
+The web server also requires a running MongoDB instance. We recommend setting this up through docker, by running `docker-compose build` and `docker-compose up` in the [`mongodb` directory](../database) of the main OpenDC repository.
+
+#### Get and configure the code
+
+Clone OpenDC and follow the [instructions in the main repository](../) to set up a Google OAuth ID and environment variables.
+
+**Important:** Be sure to set up environment variables according to those instructions, in a `.env` file.
+
+In `api/static/index.html`, add your own `OAUTH_CLIENT_ID` in `content=` on line `2`.
+
+#### Set up the database
+
+You can selectively run only the database services from the standard OpenDC `docker-compose` setup:
+
+```bash
+docker-compose build mongo mongo-express
+docker-compose up mongo mongo-express
+```
+
+This will set you up with a running MongoDB instance and a visual inspection tool running on [localhost:8082](http://localhost:8082), with which you can view and manipulate the database.
+
+### Local Development
+
+Run the server.
+
+```bash
+cd api
+python main.py
+```
+
+When editing the web server code, restart the server (`CTRL` + `c` followed by `python main.py` in the console running the server) to see the result of your changes.
+
+#### Code Style
+
+To format all files, run `format.sh` in this directory (uses `yapf` internally).
+
+To check if code style is up to modern standards, run `check.sh` in this directory (uses `pylint` internally).
+
+#### Testing
+
+Run `pytest` in this directory to run all tests.