refactor: add sequence diagrams to illustrate sign-in flows

Author: charIeszhao

docs/docs/references/using-cli/custom-ui-local-proxy.mdx

@@ -6,12 +6,70 @@ import Tabs from '@theme/Tabs';
 
 <Availability cloud oss={{ major: 1, minor: 19 }} />
 
-For Cloud users, We've made it easy to let you "Bring your own UI" to Logto. Cloud users can now upload a zip file containing the custom UI assets in Logto Console -> Sign-in experience -> Custom UI. (Check out the [Bring your UI](/docs/recipes/customize-sie/bring-your-ui) for more details.)
+For Logto Cloud users, We've made it easy to let you "Bring your own UI" to Logto. Cloud users can now upload a zip file containing the custom UI assets in Logto Console -> Sign-in experience -> Custom UI. (Check out the [Bring your UI](/docs/recipes/customize-sie/bring-your-ui) page for more details.)
 
 However, when developing such custom UI pages, users want to test and debug the code locally, before uploading to Logto Cloud. This CLI command helps you set up a local proxy and connect the following 3 entities together:
 your Logto cloud auth endpoint, your application, and your custom sign-in UI.
 
-Assuming your Cloud tenant ID is `foobar`, and you have a custom sign-in page running on dev server at `http://localhost:4000`.
+## Why do I need this?
+
+By default, when you click the "sign-in" button in your application, you will be navigated to the sign-in page configured at Logto endpoint. A successful sign-in flow can be illustrated as follows:
+
+```mermaid
+sequenceDiagram
+    box Local machine
+    participant A as Your application
+    end
+    box Logto Cloud
+    participant B as Logto Cloud auth endpoint
+    participant C as Logto sign-in page
+    end
+    A ->> B: User initiates "sign-in" action and request auth
+    B -->> A: Return auth response and tell the client<br/>to redirect to the Logto sign-in page
+    A ->> C: Redirect to the Logto sign-in page
+    C ->> B: Submit the sign-in form and<br/>request experience API to authenticate
+    B -->> C: Respond the sign-in request and<br/>tell the client to redirect to your application
+    C -->> A: Redirect to your application
+    A --> A: Handle the sign-in callback and<br/>the user is now authenticated
+```
+
+But now since you are developing your own custom sign-in UI, you need a way to navigate to the custom sign-in UI pages running on your local machine instead.
+This requires a local proxy to intercept the outgoing requests from your application and redirect them to your custom sign-in UI pages.
+
+Additionally, you need to interact with Logto's experience API to authenticate users and manage sessions.
+This proxy will also help forward these experience API requests to Logto Cloud in order to avoid CORS issues.
+
+The sequence diagram below illustrates how a successful "sign-in" flow works with your custom UI and the proxy in place:
+
+```mermaid
+sequenceDiagram
+    box Local machine
+    participant A as Your application
+    participant B as Your custom sign-in UI
+    participant C as proxy
+    end
+    box Logto Cloud
+    participant D as Logto Cloud auth endpoint
+    participant E as Logto sign-in page
+    end
+    A ->> C: User initiates "sign-in" action and request auth
+    C ->> D: Forward auth request to Logto Cloud endpoint
+    D -->> C: Return auth response andtell the client<br/>to redirect to the Logto sign-in page
+    C ->> B: Intercept the redirect and<br/>redirect to your custom sign-in page
+    B ->> C: Submit the sign-in form and<br/>request experience API to authenticate
+    C ->> D: Forward the experience API requests to Logto Cloud
+    D -->> C: Authenticate sign-in request and<br/>tell the client to redirect to your application
+    C -->> A: Redirect to your application
+    A --> A: Handle the sign-in callback and<br/>the user is now authenticated
+```
+
+With the proxy in place, you can now develop and test your custom sign-in UI locally, without needing to upload the assets to Logto Cloud every time you make a change.
+
+## Instructions
+
+### Step 1: Execute the command
+
+Assuming your Cloud tenant ID is `foobar`, and you have a custom sign-in page running on your local dev server at `http://localhost:4000`.
 
 Then you can execute the command this way:
 
@@ -34,7 +92,7 @@ npx @logto/cli proxy -p 9000 --experience-uri http://localhost:4000/ --endpoint
 
 </Tabs>
 
-It also works well if you have custom domain configured in Logto:
+It also works if you have custom domain configured in Logto:
 
 <Tabs groupId="cmd">
 
@@ -76,8 +134,28 @@ npx @logto/cli proxy -p 9000 --experience-path /path/to/your/static/files --endp
 
 </Tabs>
 
+### Step 2: Update endpoint URI in your application
+
 Finally, run your application and set its Logto endpoint to the proxy address `http://localhost:9000/` instead.
 
+Let's take a React application as an example:
+
+```tsx title=App.tsx
+import { LogtoProvider, LogtoConfig } from '@logto/react';
+
+const config: LogtoConfig = {
+  // endpoint: 'https://foobar.logto.app/', // original Logto Cloud endpoint
+  endpoint: 'http://localhost:9000/', // proxy address
+  appId: '<your-application-id>',
+};
+
+const App = () => (
+  <LogtoProvider config={config}>
+    <YourAppContent />
+  </LogtoProvider>
+);
+```
+
 If all set up correctly, when you click the "sign-in" button in your application, you should be navigated to your custom sign-in page instead of Logto's built-in UI, along with valid session (cookies) that allows you to further interact with Logto experience API.
 
 Happy coding!

src/scss/custom.scss

@@ -301,3 +301,9 @@ hr {
 code {
   tab-size: 4;
 }
+
+svg[id^='mermaid-'] {
+  rect[class='rect'] {
+    stroke: var(--logto-border);
+  }
+}