diff --git a/src/topic/README.md b/src/topic/README.md
index 5876c88f..a9d7b43f 100644
--- a/src/topic/README.md
+++ b/src/topic/README.md
@@ -14,3 +14,37 @@ Notice: This API is EXPERIMENTAL and may be changed or removed in a later releas
- Transactions
- Add context
- Graceful shutdown
+
+# State machine
+
+## Stream
+
+```mermaid
+stateDiagram
+direction LR
+[*] --> Init
+Init --> Active
+Active --> Closing
+Closing --> Closed
+Active --> Closed
+Closed --> [*]
+```
+
+## Retryer
+
+```mermaid
+stateDiagram
+direction TB
+[*] --> init
+init --> initStream
+initStream --> active
+active --> retriableError
+active --> notRetriableError
+active --> closing
+closing --> closed
+retriableError --> reinitStream
+reinitStream --> forceblyCloseExistingStream
+forceblyCloseExistingStream --> initStream
+notRetriableError --> [*]
+note right of notRetriableError : one of the possible causes of the error is the context timeout
+```