From 181455ed39ed62f4c6bdcd3c668d47d26be57ffc Mon Sep 17 00:00:00 2001
From: Vincent <vincent@ory.sh>
Date: Thu, 3 Aug 2023 17:30:11 +0200
Subject: [PATCH] fix: verification flow diagram (#1486)

---
 .../flows/verify-email-account-activation.mdx | 28 ++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/kratos/self-service/flows/verify-email-account-activation.mdx b/docs/kratos/self-service/flows/verify-email-account-activation.mdx
index cd64464b8..4488fd4c4 100644
--- a/docs/kratos/self-service/flows/verify-email-account-activation.mdx
+++ b/docs/kratos/self-service/flows/verify-email-account-activation.mdx
@@ -18,7 +18,33 @@ Ory allows users to verify email addresses associated with their accounts. This
 the address they used to create their account. If verification is enabled, Ory Identities starts the verification process
 automatically when users sign up. Users can also verify their addresses manually.
 
-The verification flow is supported in both browsers and API clients.
+The verification flow is supported in both browsers and API clients and can be summarized as the following state machine:
+
+```mdx-code-block
+import Mermaid from "@site/src/theme/Mermaid"
+
+<Mermaid
+  chart={`
+stateDiagram
+  s1: Flow is initialized
+  s2: User Interface renders Verification Flow Forms
+  s3: Update Verification Flow with Error Context(s)
+  s4: Verification challenge initiated (link or code via email)
+  s5: UI renders code input form (if code, link skips this)
+  s6: Show error message and reload form
+  s7: Verification completed
+  [*] --> s1 : User clicks "Verify Email/SMS/..."
+  s1 --> s2
+  s2 --> s4 : User provides valid verification data
+  s2 --> s3 : User provides invalid verification data
+  s3 --> s2
+  s4 --> s5
+  s5 --> s6 : Challenge response invalid
+  s5 --> s7 : Challenge response valid
+  s6 --> s5
+`}
+/>
+```
 
 :::caution