diff --git a/docs/howitworks.rst b/docs/howitworks.rst
index 45bf3cb4..54153f3c 100644
--- a/docs/howitworks.rst
+++ b/docs/howitworks.rst
@@ -395,6 +395,58 @@ presence of many machines, and would require manually splitting up the parts of
Twisted that we would like to use.
+Message Routing
+---------------
+
+At present routing is very simple, and assumes that it is impossible for a tree
+of contexts to be constructed such that at least one of a context's indirect
+parents will not know the ID of a target the context is attempting to
+communicate with.
+
+When :py:class:`econtext.core.Router` receives a message, it first checks the
+IDs associated with its directly connected streams for a potential route for
+the message. If one of the streams matches, either because the stream directly
+connects to the target ID, or the master has sent an ``ADD_ROUTE`` message
+associating that stream with the target ID, then the message will be forwarded
+down the tree using that stream.
+
+If the message does not match any ``ADD_ROUTE`` message or directly connected
+stream, instead it is forwarded upstream, first to the context's parent, and
+recursively by the each parent context in turn, until some tree node is reached
+that knows how to forward the message back down the tree.
+
+When the master establishes a new context via an existing child context, it
+takes care to send corresponding ``ADD_ROUTE`` messages to each indirect parent
+up the tree.
+
+
+Example
+#######
+
+.. image:: images/context-tree.png
+
+In the diagram, when ``master`` is establishing a connection to
+``sudo:node12b:webapp``, it must send ``ADD_ROUTE`` messages to ``rack12``,
+``dc1``, and ``bastion``; `node12b` does not require an ``ADD_ROUTE`` message
+since it has a stream directly connected to the new context.
+
+When ``sudo:node22a:webapp`` wants to send a message to
+``sudo:node12b:webapp``, the message will be routed as follows:
+
+``sudo:node22a:webapp -> node22a -> rack22 -> dc2 -> bastion -> dc1 -> rack12 -> node12b -> sudo:node12b:webapp``
+
+.. image:: images/route.png
+
+
+Future
+######
+
+The current routing approach is incomplete, since routes to downstream contexts
+are not propagated upwards when a descendant of the master context establishes
+a new child context, but that is okay for now, since child contexts cannot
+currently allocate new context IDs anyway.
+
+
Differences Between Master And Slave Brokers
############################################
diff --git a/docs/images/context-tree.graphml b/docs/images/context-tree.graphml
new file mode 100644
index 00000000..3ec973e3
--- /dev/null
+++ b/docs/images/context-tree.graphml
@@ -0,0 +1,497 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ master
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ bastion
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ dc1
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ dc2
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rack11
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rack12
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node11a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node11b
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node12a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node12b
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node21a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node21b
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node22a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node22b
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rack21
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rack22
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ sudo:node12b:webapp
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ sudo:node22a:webapp
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/images/context-tree.png b/docs/images/context-tree.png
new file mode 100644
index 00000000..eb17ee8b
Binary files /dev/null and b/docs/images/context-tree.png differ
diff --git a/docs/images/route.graphml b/docs/images/route.graphml
new file mode 100644
index 00000000..4cf55d1f
--- /dev/null
+++ b/docs/images/route.graphml
@@ -0,0 +1,637 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ master
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ bastion
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ dc1
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ dc2
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rack11
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rack12
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node11a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node11b
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node12a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node12b
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node21a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node21b
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node22a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ node22b
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rack21
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rack22
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ sudo:node12b:webapp
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ sudo:node22a:webapp
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/images/route.png b/docs/images/route.png
new file mode 100644
index 00000000..d535f847
Binary files /dev/null and b/docs/images/route.png differ