diff --git a/README.md b/README.md
index 7e3e47b3..8e939cf0 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,16 @@
 # dora-rs
 Dataflow Oriented Robotic Architecture
+
+## Python API Design
+
+The Python API is probably going to look as follows:
+```python
+@register
+async def function_name(state: DoraState, message: DoraMessage):
+    return outputs
+``` 
+
+The philosophy is to use async function as primary instance to:
+- Mitigate the risk of running undafe data mutations.
+- Managing several run at the same time with timeout / deadline capabilities
+- Using Tokio Spawn to avoid thread locks on CPU bound runs.