diff --git a/README.md b/README.md
index eb2ad95..31460f2 100644
--- a/README.md
+++ b/README.md
@@ -23,9 +23,7 @@ TODO
 ### gir.html
 * Implement a UI
 
-### Documentation
-* Document the overall architecture
-
 ### General
 * Make Gir use modules
 * Get this on NPM?
+* Move into subdirectories?
diff --git a/architecture.md b/architecture.md
new file mode 100644
index 0000000..1c898ec
--- /dev/null
+++ b/architecture.md
@@ -0,0 +1,26 @@
+Compilation pipeline
+--------------------
+
+### `compile`
+`parse` → `optimize`
+
+Parse produced IR without offsets and optimize produces flattened IR. For
+more details about Gir's IR, see `ir.md`. For more details about `compile()`
+see `api.md`
+
+### `optimize`
+`joinAdjacentOps` → `transformClearLoops` → `addOffsetProperties` →
+`transformMultiplyLoops` → `flattenLoops`
+
+For more details about optimization, see `optimizations.md`
+
+Interpreter
+-----------
+For more details about `newVM()` and `runVM()` see `api.md`
+
+### `newVM`
+Created a new VM state object that can be passed to `runVM()`
+
+### `runVM`
+Takes a VM state object, executed it, and returns a new VM state object
+describing the state after execution. The old state object is not modified