It used to be a link, now we just inline it here.

howto/gitlab.md

@@ -1608,16 +1608,56 @@ file, the `profile::gitlab::app::major_version` variable.
 <!-- a good guide to "audit" an existing project's design: -->
 <!-- https://bluesock.org/~willkg/blog/dev/auditing_projects.html -->
 
+## Architecture
+
 GitLab is a fairly large program with multiple components. The
 [upstream documentation](https://docs.gitlab.com/ee/development/architecture.html) has a good details of the architecture but
 this section aims at providing a shorter summary. Here's an overview
 diagram, first:
 
-![GitLab's architecture diagram](https://docs.gitlab.com/ee/development/img/architecture_simplified_v14_9.png)
+```mermaid
+%%{init: {"flowchart": { "useMaxWidth": false } }}%%
+graph TB
+  %% Component declarations and formatting
+  HTTP((HTTP/HTTPS))
+  SSH((SSH))
+  GitLabPages(GitLab Pages)
+  GitLabWorkhorse(GitLab Workhorse)
+  GitLabShell(GitLab Shell)
+  Gitaly(Gitaly)
+  Puma("Puma (Gitlab Rails)")
+  Sidekiq("Sidekiq (GitLab Rails)")
+  PostgreSQL(PostgreSQL)
+  Redis(Redis)
+
+  HTTP -- TCP 80,443 --> NGINX
+  SSH -- TCP 22 --> GitLabShell
+
+  NGINX -- TCP 8090 --> GitLabPages
+  NGINX --> GitLabWorkhorse
+
+  GitLabShell --> Gitaly
+  GitLabShell --> GitLabWorkhorse
+
+  GitLabWorkhorse --> Gitaly
+  GitLabWorkhorse --> Puma
+  GitLabWorkhorse --> Redis
+
+  Sidekiq --> PostgreSQL
+  Sidekiq --> Redis
+
+  Puma --> PostgreSQL
+  Puma --> Redis
+  Puma --> Gitaly
+
+  Gitaly --> GitLabWorkhorse
+```
+
 
-Note: the above image may be broken as upstream frequently changes the
-URL. It should be visible in the [Simplified component overview](https://docs.gitlab.com/ee/development/architecture.html#simplified-component-overview) of
-the [architecture documentation](https://docs.gitlab.com/ee/development/architecture.html).
+Note: the above image was copy-pasted from upstream on 2025-05-07 but
+may have changed since then. An up to date view should be visible in
+the [Simplified component overview](https://docs.gitlab.com/ee/development/architecture.html#simplified-component-overview) of the [architecture
+documentation](https://docs.gitlab.com/ee/development/architecture.html).
 
 The web frontend is Nginx (which we incidentally also use in our
 [howto/cache](howto/cache) system) but GitLab wrote their own reverse proxy called