Start to document the architecture.

2 files changed, 28 insertions, 3 deletions

diff --git a/docs/architecture.rst b/docs/architecture.rst
new file mode 100644
index 00000000..80e2c28a
--- /dev/null
+++ b/docs/architecture.rst
@@ -0,0 +1,16 @@
+Architecture
+============
+
+.. warning::
+
+    Because ``cryptography`` is so young, much of this document is
+    aspirational, rather than documentation.
+
+``cryptography`` has three different layers:
+
+* ``cryptography.c``: This package contains bindings to low level cryptographic
+  libraries. Our initial target will be OpenSSL.
+* ``cryptography.primitives``: This packages contains low level algorithms,
+  things like ``AES`` or ``SHA1``.
+* ``cryptography``: This package contains higher level recipes, for example
+  "encrypt and then MAC".
diff --git a/docs/index.rst b/docs/index.rst
index 47acbde9..9001d668 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,7 +1,16 @@
-Welcome to ``cryptography``'s documentation!
-============================================
+Welcome to ``cryptography``
+===========================
+
+.. warning::
+
+    ``cryptography`` is very young, and very incomplete.
+
+``cryptography`` is a Python library which exposes cryptographic primitives and
+recipes.
 
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
+
+    architecture