diff --git a/README.rst b/README.rst
index 4e88263066..d29c00aa7c 100644
--- a/README.rst
+++ b/README.rst
@@ -1,6 +1,6 @@
-===============================
-magnum
-===============================
+======
+Magnum
+======
 
 new Openstack project for containers.
 
@@ -8,8 +8,39 @@ new Openstack project for containers.
 * Documentation: http://docs.openstack.org/developer/magnum
 * Source: http://git.openstack.org/cgit/stackforge/magnum
 * Bugs: http://bugs.launchpad.net/magnum
+* ReST Client: http://github.com/stackforge/python-magnumclient
+
+Architecture
+------------
+
+There are four different types of objects in the Magnum system:
+
+* Bay: A physical machine or virtual machine where work is scheduled
+* Pod: A collection of containers running on one physical or virtual machine
+* Service: A port to Pod mapping
+* Container: A docker container
+
+Three binaries work together to compose the Magnum system.  The first binary
+accessed by the python-magnumclient code is the magnum-api ReST server.  The
+ReST server may run as one process or multiple processes.  When a ReST request
+is sent to the client API, the request is sent via AMQP to the magnum-backend
+process.
+
+The magnum-backend process runs on each machine where a docker server is
+running or where a k8s minion is located.  The backend processor contacts the
+appropriate backend (for the container object, docker, for the server & pod
+objects, k8s).  The backend then executes the operation requested and sends the
+results to the third binary.
+
+The third binary, magnum-conductor, reads and writes the database with
+information related to the object operated upon.  The conductor then returns
+the new object back up the call stack, where it may be used to provide
+information to the client or used for processing the operation.  There is only
+one magnum-conductor process running.
 
 Features
 --------
-
-* TODO
+* Abstractions for bays, pods, services, and containers.
+* Integration with Kubernetes and Docker for backend container technology.
+* Integration with Keystone for multi-tenant security.
+* Integraiton with Neutron for k8s multi-tenancy network security.