diff --git a/README.md b/README.md
index 67d80ae..462542c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,84 @@
-# front-desk
+keyosk
-Web application for generating, validating, and serving JSON Web Tokens over a REST API. Written in Python
+
+
+
+
+
+Keyosk is a RESTful web service that can be used to issue application-agnostic
+[JSON Web Tokens](https://jwt.io/introduction/) (JWTs).
+
+In a [microservice based architecture](https://xkcd.com/1988/), each service only
+communicates with the other services using the publicly exposed API. This promotes
+more consistent and stable APIs as well as more intentionally specialized services.
+However, when it comes to authentication this can present a problem: to ensure secure
+authentication for a microservice-based application there are only two real options:
+ * Each service must re-implement an authentication system, leading to duplicated code,
+ nonstandard interfaces, and the potential for synchronization problems
+ * The services must have access to a shared resource outside of their publicly
+ defined APIs, which is kind of against the whole idea of microservice architectures
+
+**Keyosk provides a third option:**
+
+Users can authenticate against Keyosk and be issued a JSON Web Token, which can then
+be used to authenticate against other microservices in the application. When a
+microservice receives a user-submitted JWT it can verify with the Keyosk server that
+the token a) is valid and b) hasn't been tampered with.
+
+The workflow looks something like this:
+
+1. User wants to submit a request to the *ToDo Service*
+2. User submits username and password/API key using
+ [HTTP basic auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
+ to Keyosk
+3. Keyosk validates the user's credentials and issues a JWT that encodes the users
+ permissions, then signs the JWT using its private-key.
+4. The user takes the JWT issued by Keyosk and submits their request to the
+ *ToDo Service*
+5. The *ToDo Service* queries Keyosk for its public-key and uses the public-key to
+ verify that the JWT it just received was in fact issued by Keyosk and hasn't been
+ tampered with.
+6. The *ToDo Service* decodes the JWT and is able to read the permissions information
+ for the user's account directly out of the JWT itself.
+
+The application's accounts are stored in one location, the authentication workflow is
+the same for all the application's components, and all the components communicate with
+each other over their public API.
+
+To learn more, [read the docs!](docs/)
+
+## building
+
+This project uses [Poetry](https://poetry.eustace.io/) for its build and development
+system. Please [install Poetry](https://poetry.eustace.io/docs/#installation) and run
+`poetry install` to create and populate the virtual environment.
+
+```bash
+# build python wheel and source distributions
+make build
+
+# build sphinx documentation in HTML format
+make docs
+
+# build sphinx documentation in another format
+make docs SPHINX_FORMAT=
+```
+
+## developing
+
+```bash
+# install poetry
+pip3 install poetry --user --pre
+
+# install pre-commit
+pip3 install pre-commit --user
+
+# install pre-commit hooks
+pre-commit install
+
+# create virtual environment from lockfile
+poetry install
+
+# run the tests and static analysis
+poetry run tox
+```