diff --git a/.gitignore b/.gitignore
index 9db0baa..c4cf83b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -59,3 +59,4 @@ target/
 /relay.sqlite
 /misc/node_modules/
 /docs/events.png
+/docs/states-code.png
diff --git a/docs/states-code.dot b/docs/states-code.dot
new file mode 100644
index 0000000..c32bca2
--- /dev/null
+++ b/docs/states-code.dot
@@ -0,0 +1,18 @@
+/* this state machine is just about the code */
+
+digraph {
+        need_code [label="need\ncode"]
+        asking_for_code [label="asking\nuser\nfor\ncode"]
+        creating_code [label="allocating\nnameplate"]
+        creating_code2 [label="generating\nsecret"]
+        know_code
+
+        need_code -> know_code [label="set_code()"]
+
+        need_code -> asking_for_code [label="input_code()"]
+        asking_for_code -> know_code [label="user typed code"]
+
+        need_code -> creating_code [label="get_code()"]
+        creating_code -> creating_code2 [label="rx allocation"]
+        creating_code2 -> know_code [label="generated secret"]
+}
diff --git a/src/wormhole/states.py b/src/wormhole/states.py
new file mode 100644
index 0000000..8ad8089
--- /dev/null
+++ b/src/wormhole/states.py
@@ -0,0 +1,11 @@
+
+from automat import MethodicalMachine
+
+class WormholeState(object):
+    _machine = MethodicalMachine()
+
+    @_machine.state(initial=True)
+    def start(self):
+        pass
+
+