Publish an interactive architecture diagram on cortexmetrics.io

.gitignore

@@ -10,6 +10,8 @@ website/.hugo_build.lock
 website/public
 website/resources
 website/content/en/docs
+website/static/diagrams
+tools/diagram/d3.min.js
 e2e_integration_test*
 active-query-tracker
 dist/

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 dark-mode 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:
 ---