diff --git a/apps/emqx_ds_shared_sub/README.md b/apps/emqx_ds_shared_sub/README.md
index 41a5ab407..9c4c15870 100644
--- a/apps/emqx_ds_shared_sub/README.md
+++ b/apps/emqx_ds_shared_sub/README.md
@@ -1,5 +1,14 @@
 # EMQX Durable Shared Subscriptions
 
+This application makes durable session capable to cooperatively replay messages from a topic.
+
+# General layout and interaction with session
+
+![General layout](docs/images/ds_shared_subs.png)
+
+* The nesting reflects nesting/ownership of entity states.
+* The bold arrow represent the [most complex interaction](https://github.com/emqx/eip/blob/main/active/0028-durable-shared-subscriptions.md#shared-subscription-session-handler), between session-side group subscription state machine and the shared subscription leader.
+
 # Contributing
 
 Please see our [contributing.md](../../CONTRIBUTING.md).
diff --git a/apps/emqx_ds_shared_sub/docs/images/ds_shared_subs.png b/apps/emqx_ds_shared_sub/docs/images/ds_shared_subs.png
new file mode 100644
index 000000000..ae138d5b1
Binary files /dev/null and b/apps/emqx_ds_shared_sub/docs/images/ds_shared_subs.png differ