docs: Add end-to-end architecture diagram (#1005)

Author: mykola-mokhnach

README.md

@@ -10,6 +10,8 @@ Appium UiAutomator2 Driver is a test automation framework for Android devices. A
 
 UiAutomator2 Driver proxies most of the commands to [UiAutomator2 server](https://github.com/appium/appium-uiautomator2-server), which uses Google's [UiAutomator](https://developer.android.com/training/testing/ui-automator) framework under the hood. Some commands are proxied directly to [appium-adb](https://github.com/appium/appium-adb) and other helpers built on top of Android platform tools.
 
+See the [end-to-end architecture diagram](./docs/architecture.md).
+
 > [!IMPORTANT]
 > Since major version *5.0.0*, this driver is only compatible with Appium 3. Use the `appium driver install uiautomator2`
 > command to add it to your distribution.

docs/architecture.md

@@ -0,0 +1,34 @@
+# Architecture
+
+```mermaid
+flowchart TD
+  subgraph ClientSide["Test Client"]
+    T["Test Code"]
+    CL["Appium Client Library<br/>(Java / Python / JS / Ruby / C#)"]
+  end
+
+  subgraph ServerHost["Automation Host"]
+    AS["Appium Server<br/>WebDriver HTTP API"]
+    XD["UiAutomator2 Driver<br/>(appium-uiautomator2-driver)"]
+    ADBM["ADB + Port Forwarding"]
+    CDM["Chromedriver Management<br/>(hybrid / webview only)"]
+  end
+
+  subgraph DeviceTarget["Android Device / Emulator"]
+    U2S["UiAutomator2 Server<br/>(instrumentation HTTP API)"]
+    UIA["UiAutomator Framework"]
+    CD["Chromedriver<br/>(in webview context)"]
+    AUT["Application Under Test"]
+  end
+
+  T --> CL
+  CL -->|"W3C WebDriver over HTTP"| AS
+  AS -->|"Forwards session commands to driver"| XD
+  XD -->|"Install, shell, forward ports"| ADBM
+  XD -->|"Context switch to WEBVIEW_*"| CDM
+  ADBM -->|"adb forward (e.g. host:8200 → device:6790)"| U2S
+  CDM -->|"Chromedriver HTTP"| CD
+  U2S -->|"UiAutomator APIs"| UIA
+  UIA -->|"UI interactions + accessibility tree"| AUT
+  CD -->|"WebDriver in webview"| AUT
+```