From 33fa259f4d2d7fc30d8e23ce80e3fe3e02c797dd 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 | 64 +++++++++++++++++++++++++++++++
 mkdocs.yml                        |  1 +
 2 files changed, 65 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..22f947d2b
--- /dev/null
+++ b/docs/design-guide/architecture.md
@@ -0,0 +1,64 @@
+# 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)"]:::external
+
+    subgraph global["Global Cluster"]
+        Dex["Dex<br/>(OIDC Broker)"]:::otheross
+        Nautobot["Nautobot<br/>(Network Source of Truth)"]:::otheross
+        Keystone["Keystone<br/>(Identity Service)"]:::openstack
+    end
+
+    subgraph site["Site Cluster(s)"]
+        Ironic["Ironic<br/>(Bare Metal)"]:::openstack
+        Placement["Placement"]:::openstack
+        Neutron["Neutron<br/>(Networking)"]:::openstack
+        Glance["Glance<br/>(Images)"]:::openstack
+        Nova["Nova<br/>(Compute)"]:::openstack
+        Cinder["Cinder<br/>(Block Storage)"]:::openstack
+    end
+
+    subgraph legend["Key"]
+        OS_KEY["OpenStack Service"]:::openstack
+        OSS_KEY["Other Open Source"]:::otheross
+        EXT_KEY["External System"]:::external
+    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
+
+    classDef openstack fill:#fed7aa,stroke:#ea580c,color:#000
+    classDef otheross fill:#bfdbfe,stroke:#3b82f6,color:#000
+    classDef external fill:#e2e8f0,stroke:#64748b,color:#000
+```
+
+## 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 2902929e6..7ce00d935 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