diff --git a/docs/architecture-diagrams.py b/docs/architecture-diagrams.py
new file mode 100644
index 0000000..1e1eb78
--- /dev/null
+++ b/docs/architecture-diagrams.py
@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""
+Generate architecture diagrams for the documentation
+"""
+from diagrams import Diagram, Edge, Cluster
+from diagrams.k8s.compute import Deployment, Pod
+from diagrams.k8s.network import Service
+from diagrams.k8s.storage import PVC
+
+IMAGES_DIR = "source/_static/images"
+
+with Diagram("JupyterHub + SSH + SFTP", show=False, outformat="png", filename=f"{IMAGES_DIR}/architecture") as diag:
+    autohttps = Deployment("autohttps")
+    ssh = autohttps >> Edge(label="port 22") >> Deployment("jupyterhub-ssh")
+    sftp = autohttps >> Edge(label="port 2222") >> Deployment("jupyterhub-sftp")
+
+    homedirs = PVC("home directories")
+
+    sftp - homedirs
+
+    with Cluster("jupyterhub"):
+        hub = Deployment("hub/proxy")
+
+        hub_svc = autohttps >> Edge(label="port 80") >> hub
+
+        ssh >> Edge(label="start server if needed", style="bold") >> hub
+
+        users = [Pod(f"user{i}") for i in range(2)]
+
+        for user in users:
+            user - homedirs
+
+        for user in users:
+            ssh - Edge(label="console via terminado", color="red", style="bold") - user
+        hub >> users
diff --git a/docs/requirements.txt b/docs/requirements.txt
index ed0159c..fee1854 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -3,3 +3,4 @@ sphinx-book-theme
 myst_parser[sphinx]
 sphinx-copybutton
 sphinx<3
+diagrams
diff --git a/docs/source/_static/images/architecture.png b/docs/source/_static/images/architecture.png
new file mode 100644
index 0000000..0812609
Binary files /dev/null and b/docs/source/_static/images/architecture.png differ