Publish an interactive architecture diagram on cortexmetrics.io

.gitignore

@@ -10,6 +10,7 @@ website/.hugo_build.lock
 website/public
 website/resources
 website/content/en/docs
+website/static/diagrams
 e2e_integration_test*
 active-query-tracker
 dist/

CHANGELOG.md

@@ -54,6 +54,7 @@
 * [ENHANCEMENT] Compactor: Reduce object storage GET calls when updating the bucket index by skipping re-reading parquet converter markers for blocks that already have a valid-version parquet entry in the previous index. #7669
 * [ENHANCEMENT] Upgrade Thanos and promql-engine to latest. #7740
 * [ENHANCEMENT] Ruler: Adjust ruler frontend decoder to not wrap query error messages with execution prefix, this makes error responses consistent between internal and external ruler paths. #7741
+* [ENHANCEMENT] Docs: Add an interactive architecture diagram at `/diagrams/cortex-architecture.html`, linked from the new Interactive Diagram documentation page. It replaces the static `images/architecture.png` embed in the architecture documentation and shows the protocol, endpoint, hash ring and source file behind each component and hop. #7769
 * [BUGFIX] Querier: Fix queryWithRetry and labelsWithRetry returning (nil, nil) on cancelled context by propagating ctx.Err(). #7370
 * [BUGFIX] Metrics Helper: Fix non-deterministic bucket order in merged histograms by sorting buckets after map iteration, matching Prometheus client library behavior. #7380
 * [BUGFIX] Distributor: Return HTTP 401 Unauthorized when tenant ID resolution fails in the Prometheus Remote Write 2.0 path. #7389

VENDORED_CODE.md

@@ -16,3 +16,10 @@ in the ./vendor/ directory:
 
 [One file used in tests](COPYING.LGPL-3) is under LGPL-3, that's why we ship
 the license text in this repository.
+
+Outside of ./vendor/, [tools/diagram/d3.min.js](tools/diagram/d3.min.js) is an
+unmodified copy of [D3](https://d3js.org/) 7.9.0, which is under the ISC license
+(Copyright 2010-2023 Mike Bostock). It is vendored so the interactive
+architecture diagram renders offline and the documentation site makes no
+third-party request; see [tools/diagram/readme.md](tools/diagram/readme.md) for
+its provenance.

docs/architecture-diagram.md

@@ -0,0 +1,34 @@
+---
+title: "Interactive Architecture Diagram"
+linkTitle: "Interactive Diagram"
+weight: 3
+slug: architecture-diagram
+---
+
+The [interactive architecture diagram](../tools/diagram/cortex-architecture.html)
+draws the same system [Architecture](./architecture.md) describes in prose, with the
+details attached to the picture instead of scattered through the text. It covers
+the write path, the read path, the blocks lifecycle and the optional services —
+ruler, alertmanager, compactor, store-gateway, query-scheduler and the caches.
+Hover a connector and it names the protocol and the endpoint that hop actually
+uses; select a component and it gives you the role, whether it is stateful, which
+hash ring it joins, the endpoints it serves, its `-target` value and the file in
+the Cortex tree that implements it.
+
+Three toggles cover the places where the topology genuinely forks, rather than
+drawing one deployment and calling it typical: the query-frontend's own queue
+versus a separate query-scheduler, the ruler evaluating rules in its own querier
+stack versus delegating to the query-frontend with `-ruler.frontend-address`, and
+the parquet queryable off versus on. There are also guided walkthroughs that step
+through the write, read, rule-evaluation and blocks flows one hop at a time, a
+table view of every component and flow, and a light/dark theme toggle.
+
+The diagram's metadata is hand-maintained against the Cortex source rather than
+generated from it, so the `src` path shown in each component's panel is the
+authority — if a ring key, prefix or endpoint disagrees with the code, the code is
+right and the diagram needs fixing. It also deliberately shows a few things the
+prose does not yet cover, such as the OTLP ingest endpoint and the
+parquet-converter, which is marked experimental for that reason. Its source lives
+in [`tools/diagram/`](https://github.com/cortexproject/cortex/tree/master/tools/diagram).
+
+**[Open the interactive architecture diagram →](../tools/diagram/cortex-architecture.html)**

docs/architecture.md

@@ -7,9 +7,7 @@ slug: architecture
 
 Cortex consists of multiple horizontally scalable microservices. Each microservice uses the most appropriate technique for horizontal scaling; most are stateless and can handle requests for any users while some (namely the [ingesters](#ingester)) are semi-stateful and depend on consistent hashing. This document provides a basic overview of Cortex's architecture.
 
-The following diagram does not include all the Cortex services, but does represent a typical deployment topology.
-
-<p align="center"><img src="../images/architecture.png" alt="Cortex Architecture"></p>
+The [interactive architecture diagram](./architecture-diagram.md) draws the same system, and does include the services this document leaves out. Hover a connector for the protocol and endpoint of that hop; select a component for its hash ring, endpoints and source file.
 
 ## The role of Prometheus
 

docs/blocks-storage/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "Blocks Storage"
 linkTitle: "Blocks Storage"
-weight: 3
+weight: 4
 menu:
 ---