From a052b00dacf73e4da9163f649d69fb936a166fe3 Mon Sep 17 00:00:00 2001
From: Doug Goldstein <doug.goldstein@rackspace.com>
Date: Fri, 3 Apr 2026 15:57:14 -0500
Subject: [PATCH] docs: create a diagram to show how the components connect

This diagram shows how the components connect and authenticate to each
other.
---
 docs/design-guide/architecture.md | 54 +++++++++++++++++++++++++++++++
 mkdocs.yml                        |  1 +
 2 files changed, 55 insertions(+)
 create mode 100644 docs/design-guide/architecture.md

diff --git a/docs/design-guide/architecture.md b/docs/design-guide/architecture.md
new file mode 100644
index 000000000..9a974b8eb
--- /dev/null
+++ b/docs/design-guide/architecture.md
@@ -0,0 +1,54 @@
+# Architecture Overview
+
+UnderStack is split across two cluster types: a **global cluster** hosting shared
+services, and one or more **site clusters** hosting the OpenStack compute plane.
+
+## Service Layout
+
+```mermaid
+graph TB
+    IDP["External Identity Provider<br/>(e.g. Azure Entra / LDAP)"]
+
+    subgraph global["Global Cluster"]
+        Dex["Dex<br/>(OIDC Broker)"]
+        Nautobot["Nautobot<br/>(Network Source of Truth)"]
+        Keystone["Keystone<br/>(Identity Service)"]
+    end
+
+    subgraph site["Site Cluster(s)"]
+        Ironic["Ironic<br/>(Bare Metal)"]
+        Placement["Placement"]
+        Neutron["Neutron<br/>(Networking)"]
+        Glance["Glance<br/>(Images)"]
+        Nova["Nova<br/>(Compute)"]
+        Cinder["Cinder<br/>(Block Storage)"]
+    end
+
+    IDP -->|"authenticates users"| Dex
+    Dex -->|"OIDC"| Nautobot
+    Dex -->|"OIDC"| Keystone
+
+    Keystone -->|"auth token validation"| Ironic
+    Keystone -->|"auth token validation"| Placement
+    Keystone -->|"auth token validation"| Neutron
+    Keystone -->|"auth token validation"| Glance
+    Keystone -->|"auth token validation"| Nova
+    Keystone -->|"auth token validation"| Cinder
+```
+
+## Authentication Flow
+
+All user authentication is brokered through **Dex**, which acts as an OIDC
+federation layer in front of your external Identity Provider (IdP). This means
+you only need to configure your IdP connection once in Dex, and all services
+inherit that integration.
+
+- **Nautobot** uses Dex for SSO, allowing operators to log in with their
+  corporate credentials.
+- **Keystone** is configured with Dex as its OIDC provider, so all OpenStack
+  API access and dashboard logins flow through Dex to the external IdP.
+
+Once a user is authenticated via Keystone, the resulting token is trusted by
+all site cluster OpenStack services (Ironic, Placement, Neutron, Glance, Nova,
+Cinder). Those services validate tokens against Keystone but do not interact
+with Dex or the external IdP directly.
diff --git a/mkdocs.yml b/mkdocs.yml
index 104d45149..9d5c0888e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -128,6 +128,7 @@ nav:
       - component-ansible.md
   - 'Design Guide':
     - design-guide/intro.md
+    - design-guide/architecture.md
     - design-guide/add-remove-app.md
     - 'Hardware Definitions':
       - design-guide/device-types.md