From d2840f33283f7e9beea1211fa3c55b24c2cb91a4 Mon Sep 17 00:00:00 2001
From: Christine Dodrill <me@christine.website>
Date: Wed, 17 Jan 2018 08:45:14 -0800
Subject: [PATCH] doc: new document on the theory of routed, incomplete

---
 doc/theory.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 doc/theory.md

diff --git a/doc/theory.md b/doc/theory.md
new file mode 100644
index 0000000..544a4d9
--- /dev/null
+++ b/doc/theory.md
@@ -0,0 +1,61 @@
+# Theory of route
+
+## Why does this project exist?
+
+HTTP load balancing is harder than it needs to be. Existing projects assume
+there is a direct line-of-fire from the load balancer to the underlying services.
+This is NOT always true. Containerization has lead to a lot of hacks such as
+overlay networks to offer this direct line-of-fire so that the load balancer
+can make a direct TCP connection to the underlying services.
+
+Route exists to invert this problem.
+
+In most networks, it is true that it is a lot easier to guarantee the backends
+have a direct line-of-fire to the load balancer, not the other way around.
+Why not just make a connection to the load balancer and re-use it for HTTP
+traffic?
+
+Route allows you to simplify your network architecture by removing the
+requirement that all backend services need a direct TCP line-of-fire to the
+load balancer. Route allows you to host HTTP services behind NAT. Route
+allows you to throw out overlay networks and return to a simpler cluster layout.
+
+## How does route work?
+
+Route has several basic nouns, they are:
+
+- route
+- backend
+- balancer
+- agent
+
+They are inter-related like this:
+
+```graphviz
+digraph G {
+    balancer -> agent
+    agent -> balancer
+    agent -> backend
+    backend -> agent
+
+    user -> balancer
+    balancer -> user
+}
+```
+
+### route
+
+A route is a combination of HTTP domain and path (currently unsupported, so
+assume `/`). An example route would be `cloudsdale.cf/`. This maps to the
+location users get.
+
+### backend
+
+A backend is the underlying service being proxied to by route. An example backend
+is Apache, Nginx or anything else that serves compliant HTTP/1.1 traffic.
+
+### balancer
+
+A balancer is an instance of `cmd/routed` running on some server somewhere.
+Balancers accept both agent and HTTP connections, proxying requests from the HTTP
+connections to agent connections and back.