diff --git a/READMEs/README.lifecycle.md b/READMEs/README.lifecycle.md
new file mode 100644
index 000000000..eb029b42f
--- /dev/null
+++ b/READMEs/README.lifecycle.md
@@ -0,0 +1,43 @@
+# lws lifecycles
+
+## Context
+
+![context lifecycle](/doc-assets/lifecycle-context.png)
+
+## Client wsi
+
+![client wsi](/doc-assets/lifecycle-wsi.png)
+
+## Server wsi
+
+![server wsi](/doc-assets/lifecycle-server-wsi.png)
+
+## role-specific events
+
+role|client|server
+---|---|---
+http COMPLETED|`LWS_CALLBACK_COMPLETED_CLIENT_HTTP`|-
+http RECEIVE|`LWS_CALLBACK_RECEIVE_CLIENT_HTTP`|`LWS_CALLBACK_RECEIVE_HTTP`
+http WRITEABLE|`LWS_CALLBACK_CLIENT_HTTP_WRITEABLE`|`LWS_CALLBACK_HTTP_WRITEABLE`
+http CLOSE|`LWS_CALLBACK_CLOSED_CLIENT_HTTP`|`LWS_CALLBACK_CLOSED_HTTP`
+http BIND|`LWS_CALLBACK_CLIENT_HTTP_BIND_PROTOCOL`|`LWS_CALLBACK_HTTP_BIND_PROTOCOL`
+http DROP|`LWS_CALLBACK_CLIENT_HTTP_DROP_PROTOCOL`|`LWS_CALLBACK_HTTP_DROP_PROTOCOL`
+
+role|client|server
+---|---|---
+ws ESTABLISHED|`LWS_CALLBACK_CLIENT_ESTABLISHED`|`LWS_CALLBACK_ESTABLISHED`
+ws RECEIVE|`LWS_CALLBACK_CLIENT_RECEIVE`|`LWS_CALLBACK_RECEIVE`
+ws WRITEABLE|`LWS_CALLBACK_CLIENT_WRITEABLE`|`LWS_CALLBACK_SERVER_WRITEABLE`
+ws CLOSE|`LWS_CALLBACK_CLIENT_CLOSED`|`LWS_CALLBACK_CLOSED`
+ws BIND|`LWS_CALLBACK_WS_CLIENT_BIND_PROTOCOL`|`LWS_CALLBACK_WS_BIND_PROTOCOL`
+ws DROP|`LWS_CALLBACK_WS_CLIENT_DROP_PROTOCOL`|`LWS_CALLBACK_WS_DROP_PROTOCOL`
+
+role|client|server
+---|---|---
+raw ESTABLISHED|`LWS_CALLBACK_RAW_CONNECTED`|`LWS_CALLBACK_RAW_ADOPT`
+raw RECEIVE|`LWS_CALLBACK_RAW_RX`|`LWS_CALLBACK_RAW_RX`
+raw WRITEABLE|`LWS_CALLBACK_RAW_WRITEABLE`|`LWS_CALLBACK_RAW_WRITEABLE`
+raw CLOSE|`LWS_CALLBACK_RAW_CLOSE`|`LWS_CALLBACK_RAW_CLOSE`
+raw BIND|`LWS_CALLBACK_RAW_SKT_BIND_PROTOCOL`|`LWS_CALLBACK_RAW_SKT_BIND_PROTOCOL`
+raw DROP|`LWS_CALLBACK_RAW_SKT_DROP_PROTOCOL`|`LWS_CALLBACK_RAW_SKT_DROP_PROTOCOL`
+
diff --git a/doc-assets/lifecycle-context.png b/doc-assets/lifecycle-context.png
new file mode 100644
index 000000000..bf92b76b5
Binary files /dev/null and b/doc-assets/lifecycle-context.png differ
diff --git a/doc-assets/lifecycle-server-wsi.png b/doc-assets/lifecycle-server-wsi.png
new file mode 100644
index 000000000..f41164c30
Binary files /dev/null and b/doc-assets/lifecycle-server-wsi.png differ
diff --git a/doc-assets/lifecycle-wsi.png b/doc-assets/lifecycle-wsi.png
new file mode 100644
index 000000000..4db2d3713
Binary files /dev/null and b/doc-assets/lifecycle-wsi.png differ