Enrich Hybrid Mesh Platform docs with fuller narrative.

Align depth with the platform-hub-spoke-config site: journey intro,
end-to-end flows, Skupper listeners, gateway circuit breaking, and
expanded observability and scaffolding guidance.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: maximilianoPizarro

content/patterns/hybrid-mesh-platform/_index.md

@@ -35,31 +35,33 @@ contributor:
 
 **Maintainer:** Maximiliano Pizarro, Specialist Solution Architect at Red Hat
 
-This platform deploys in one `helm upgrade`, connects three OpenShift clusters (hub + east + west), and shows IoT sensor data across Grafana and Developer Hub within about 30 minutes. The pages below follow one continuous story — concept, install, operate, scaffold — so you can read straight through or jump to any chapter.
+> **Your journey:** This platform deploys in one `helm upgrade`, connects three OpenShift clusters (hub + east + west), and shows IoT sensor data across Grafana and Developer Hub within about 30 minutes. The pages below follow one continuous story — concept, install, operate, scaffold — so you can read straight through or jump to any chapter.
 
-Multi-cluster GitOps platform using Red Hat products — a hub-spoke topology that centralizes governance with Red Hat Advanced Cluster Management (ACM), delivers [Industrial Edge](/patterns/industrial-edge/) workloads on regional spokes, uses OpenShift Service Mesh in ambient mode for east-west connectivity, layers Connectivity Link (Kuadrant) for API-aware ingress policy, exposes Grafana dashboards for cross-cluster visibility, and integrates Advanced Cluster Security (ACS) for vulnerability and runtime protection.
+**Hybrid Mesh Platform** is a multi-cluster GitOps platform using Red Hat products. It implements a hub-spoke topology that centralizes governance with Red Hat Advanced Cluster Management (ACM), delivers [Industrial Edge](/patterns/industrial-edge/) workloads on regional spokes, uses OpenShift Service Mesh in ambient mode for east-west connectivity, layers Connectivity Link (Kuadrant) for API-aware ingress policy, exposes Grafana dashboards for cross-cluster visibility, and integrates Advanced Cluster Security (ACS) for vulnerability and runtime protection.
 
-**Supported on:** Red Hat OpenShift Container Platform 4.20 (and 4.14 or newer per cluster).
+**Supported on:** Red Hat OpenShift Container Platform 4.20 (4.14 or newer per cluster).
 
-Read **concept → mechanics → operations**: start with [Architecture](architecture), install via [Getting Started](getting-started), scaffold workloads via [Scaffolding](scaffolding), then use platform chapters (Hub Gateway, Observability, Industrial Edge) before drilling into the pattern repository.
+Read **concept → mechanics → operations**: start with [Architecture](architecture), install via [Getting Started](getting-started), scaffold workloads via [Scaffolding](scaffolding), then use platform chapters (**Hub Gateway**, **Observability**, **Industrial Edge**) before drilling into the [pattern repository](https://github.com/maximilianopizarro/platform-hub-spoke-config).
 
 ## Overview
 
 This repository models a **GitOps-first platform** where:
 
-- **Hub cluster** runs ACM, OpenShift GitOps (Argo CD), observability aggregation, Developer Hub, ACS Central, Mailpit for notifications, and gateway-style HTTP routing with circuit breaking for shared services.
-- **Spoke clusters** (east/west regions) host **Industrial Edge** workloads: sensor and MQTT-style ingestion, Kafka pipelines, optional ML scoring, and dashboards fed by Prometheus-compatible metrics.
+- **Hub cluster** runs ACM, OpenShift GitOps (Argo CD), observability aggregation, Developer Hub, ACS Central, Mailpit for notifications, and gateway-style HTTP routing with **circuit breaking** for shared services.
+- **Spoke clusters** (east/west regions) host **Industrial Edge** patterns: sensor and MQTT-style ingestion, Kafka pipelines, optional ML scoring, and dashboards fed by Prometheus-compatible metrics.
 - **Service Mesh 3 ambient** reduces sidecar overhead while retaining ztunnel-based L4 and waypoint-based L7 policy where needed.
-- **Hub Gateway** splits traffic into front and API services per spoke, with per-service **circuit breaking** via `DestinationRule`.
-- **Service Interconnect (Skupper)** bridges spoke services and metrics to the hub via a Virtual Application Network, without VPN or firewall changes.
+- **Hub Gateway** splits traffic into **front** and **API** services per spoke, with per-service **circuit breaking** via `DestinationRule`.
+- **Service Interconnect (Skupper)** bridges spoke services and metrics to the hub via a Virtual Application Network (VAN), without VPN or firewall changes.
 - **Spoke Gateways** aggregate Industrial Edge services per spoke for simplified cross-cluster exposure.
 - **Kiali + OSSM Console** provides service mesh topology visualization on every cluster via the OpenShift Console plugin.
 - **Grafana dashboards** roll up cluster and application signals from all clusters.
 - **ACS** provides centralized policy, CVE visibility, and SecuredCluster agents on spokes.
 
 [![Platform hub-spoke overview](/images/hybrid-mesh-platform/arch-overview.png)](/images/hybrid-mesh-platform/arch-overview.png)
 
-_Hub cluster aggregates observability and Developer Hub; east and west spokes run Industrial Edge workloads connected via Service Interconnect (Skupper)._
+_Hub cluster aggregates observability and Developer Hub; east and west spokes run Industrial Edge workloads connected via Service Interconnect (Skupper). Click the image to open the full diagram._
+
+Architecture diagrams in this documentation illustrate Git, ACM, Skupper VAN, and Industrial Edge placement on east/west — use them as the visual companion to the install chapters.
 
 ## Quick links
 
@@ -71,16 +73,20 @@ _Hub cluster aggregates observability and Developer Hub; east and west spokes ru
 | Observability | [Observability](observability) |
 | Industrial Edge (multi-cluster) | [Industrial Edge](industrial-edge) |
 | Scaffolding | [Scaffolding](scaffolding) |
-| Customization | [Ideas for customization](ideas-for-customization) |
+| Branch strategy and customization | [Ideas for customization](ideas-for-customization) |
 
 ## Recommended reading order
 
-1. [Architecture](architecture) — mental model of hub, spokes, GitOps, and observability
-2. [Getting Started](getting-started) — bring clusters under GitOps
+1. [Architecture](architecture) — mental model of hub, spokes, GitOps, Skupper, and observability
+2. [Getting Started](getting-started) — bring clusters under GitOps (includes ACM + ApplicationSet detail)
 3. [Scaffolding](scaffolding) — deploy Industrial Edge instances on east/west from Developer Hub
 4. [Hub Gateway](hub-gateway) — weighted ingress and circuit breaking across spokes
 5. [Observability](observability) — Grafana, Kiali, Kafka Console
-6. [Industrial Edge](industrial-edge) — factory data pipeline on multiple spokes
+6. [Industrial Edge](industrial-edge) — factory data pipeline: sensors, Kafka, Camel, ML on multiple spokes
+
+Screenshots and architecture diagrams in the pattern repository support full-screen review — handy after deploying dashboards and verifying cross-cluster traffic.
+
+**Next →** [Architecture](architecture) — understand how Git, ACM, and Skupper wire the three clusters together.
 
 ## Red Hat products used
 
@@ -96,3 +102,5 @@ _Hub cluster aggregates observability and Developer Hub; east and west spokes ru
 - Red Hat OpenShift Pipelines (Tekton)
 - Red Hat Developer Hub (Backstage)
 - Red Hat Service Interconnect (Skupper)
+- Mailpit (SMTP testing for notifications)
+- Observability stack (Prometheus-compatible metrics, Grafana, OpenTelemetry, Kiali)

content/patterns/hybrid-mesh-platform/architecture.md

@@ -6,9 +6,11 @@ aliases: /hybrid-mesh-platform/architecture/
 
 # Architecture
 
+Understand how Git, ACM, Service Interconnect, and Industrial Edge wire the hub and spoke clusters together before you install or scaffold workloads.
+
 ## Hub-spoke theory in multi-cluster Kubernetes
 
-In multi-cluster Kubernetes, a hub-spoke model designates one administrative cluster (the hub) and one or more workload clusters (spokes). The hub owns fleet APIs: cluster inventory, policy placement, credentials for spoke registration, and often centralized GitOps controllers that fan out desired state.
+In multi-cluster Kubernetes, a hub-spoke model designates one administrative cluster (the **hub**) and one or more workload clusters (**spokes**). The hub owns fleet APIs: cluster inventory, policy placement, credentials for spoke registration, and often centralized GitOps controllers that fan out desired state.
 
 Spokes remain the execution venues for application namespaces, data-plane components (Kafka, MQTT bridges, mesh dataplane), and regional isolation for latency, data residency, or blast-radius control.
 
@@ -18,29 +20,45 @@ Spokes remain the execution venues for application namespaces, data-plane compon
 | --- | --- |
 | Centralized management | One control plane for membership, RBAC patterns, and bulk upgrades. |
 | Policy enforcement | Kubernetes policies, compliance checks, and security baselines propagate from the hub. |
-| Observability | Aggregated metrics, logging, and tracing strategies start at the hub and uniform dashboards span spokes. |
+| Observability | Aggregated metrics, logging, and tracing strategies start at the hub; uniform dashboards span spokes. |
 | GitOps consistency | A single Git revision strategy (with branch or overlay variants) drives spoke drift correction. |
 
 ## Platform architecture overview
 
-Single `main` branch: hub chart at `.`, spoke charts at `east/` and `west/`, shared `components/` referenced by all clusters.
+The pattern repository uses a **single `main` branch** with cluster-specific directories:
+
+- Hub chart at `.` (repository root)
+- Spoke charts at `east/` and `west/`
+- Shared Helm charts under `components/` referenced by hub and spoke Application CRs
 
 [![Platform architecture overview](/images/hybrid-mesh-platform/arch-overview.png)](/images/hybrid-mesh-platform/arch-overview.png)
 
 [![Hub-spoke GitOps flow](/images/hybrid-mesh-platform/arch-hub-spoke-flow.png)](/images/hybrid-mesh-platform/arch-hub-spoke-flow.png)
 
 ## Follow the request — one temperature reading end to end
 
-When a machine sensor on the east spoke publishes a temperature sample, the path is: MQTT (`messaging` broker) → Camel K (`mqtt-to-kafka` integration) → Kafka (`dev-cluster` topic) → optional ML scoring (KServe) → line-dashboard WebSocket consumer. In parallel, Thanos Querier on east scrapes Istio and Kafka metrics; a Skupper Connector (`prometheus-east`) tunnels HTTP to the hub, where Grafana datasource `prometheus-east` plots the series. The Hub Gateway can route browser traffic to the east line-dashboard via spoke-gateway and Skupper listener `ie-gateway-east`. Developer Hub Topology shows the same pods when the catalog entity carries `backstage.io/kubernetes-cluster: east` and spoke API tokens are synced.
+When a machine sensor on the **east** spoke publishes a temperature sample, the path is:
+
+1. MQTT (`messaging` broker) → Camel K (`mqtt-to-kafka` integration)
+2. Kafka (`dev-cluster` topic) → optional ML scoring (KServe)
+3. `line-dashboard` WebSocket consumer
+
+In parallel:
+
+- Thanos Querier on east scrapes Istio and Kafka metrics
+- Skupper Connector `prometheus-east` tunnels HTTP to the hub
+- Hub Grafana datasource `prometheus-east` plots the series
+- Hub Gateway routes browser traffic to the east line-dashboard via spoke-gateway and Skupper listener `ie-gateway-east`
+- Developer Hub Topology shows the same pods when the catalog entity carries `backstage.io/kubernetes-cluster: east` and spoke API tokens are synced
 
 [![End-to-end data flow](/images/hybrid-mesh-platform/arch-data-flow.png)](/images/hybrid-mesh-platform/arch-data-flow.png)
 
 ## Components on the hub vs spokes
 
 | Area | Hub | Spokes | Config path |
-| --- | --- | --- | --- |
+| --- | :---: | :---: | --- |
 | ACM hub operator & APIs | yes | | `values.yaml` |
-| ArgoCD / App-of-Apps root | yes | yes | `.` / `east/` / `west/` |
+| Argo CD / App-of-Apps root | yes | yes | `.` / `east/` / `west/` |
 | ApplicationSet (spoke apps) | yes | | `values.yaml` |
 | ACS Central | yes | | `values.yaml` |
 | ACS Secured Cluster | | yes | `east/` `west/` |
@@ -61,48 +79,106 @@ When a machine sensor on the east spoke publishes a temperature sample, the path
 | Kubecost (agent) | | yes | `east/` `west/` |
 | Kafka Console (all clusters) | yes | | `values.yaml` |
 
+Industrial Edge components exist **only** in spoke charts. The hub chart never includes factory workloads.
+
 ## GitOps application delivery flow
 
-Hub syncs first; ApplicationSet pushes per-spoke charts; each spoke Argo CD reconciles child Applications locally.
+1. Hub Argo CD syncs the root Application (operators, ACM, gateway, observability).
+2. ACM ApplicationSet reads PlacementDecision and pushes `east/` and `west/` to remote clusters.
+3. Each spoke Argo CD reconciles child Applications locally (namespaces → operators → workloads).
 
 [![GitOps sync sequence](/images/hybrid-mesh-platform/arch-gitops-sync-sequence.png)](/images/hybrid-mesh-platform/arch-gitops-sync-sequence.png)
 
+Remote deployment model:
+
+```
+Hub Argo CD → ApplicationSet
+  → east-spoke-components (source: east/, destination: east cluster)
+       → east/templates/ generates child Application CRs
+            → East Argo CD syncs child apps locally
+  → west-spoke-components (source: west/, destination: west cluster)
+       → west/templates/ generates child Application CRs
+            → West Argo CD syncs child apps locally
+```
+
 ## Sync wave ordering
 
-Components deploy in strict order via ArgoCD sync waves:
+Components deploy in strict order via Argo CD sync waves. Lower waves complete before higher waves start.
 
 [![Sync wave ordering](/images/hybrid-mesh-platform/arch-sync-waves.png)](/images/hybrid-mesh-platform/arch-sync-waves.png)
 
-Sync waves prevent operators from racing workloads — mesh and namespaces land before Industrial Edge and gateways.
+Sync waves prevent operators from racing workloads — mesh and namespaces land before Industrial Edge and gateways. Typical progression:
 
-## Service Interconnect (Skupper) topology
+1. Namespaces and RBAC
+2. Operator subscriptions (ACM, GitOps, Service Mesh, Skupper, and others)
+3. Platform services (Developer Hub, ACS, interconnect sites)
+4. Observability stack
+5. Industrial Edge and gateway workloads
 
-Red Hat Service Interconnect creates a Virtual Application Network (VAN) that bridges services across clusters without VPN or direct network connectivity.
+## Service Interconnect (Skupper) topology
 
-Connectors expose spoke-gateway and prometheus-auth-proxy; Listeners materialize ClusterIP services on the hub.
+Red Hat Service Interconnect creates a **Virtual Application Network (VAN)** that bridges services across clusters without VPN tunnels, direct routes, or firewall changes. Skupper exposes spoke Industrial Edge services and Prometheus metrics to the hub for centralized observability and ingress.
 
 [![Skupper topology](/images/hybrid-mesh-platform/arch-skupper-topology.png)](/images/hybrid-mesh-platform/arch-skupper-topology.png)
 
 [![Service Interconnect console topology](/images/hybrid-mesh-platform/service-interconnect-console-topology.png)](/images/hybrid-mesh-platform/service-interconnect-console-topology.png)
 
-## Spoke gateway aggregation
+### Hub listeners (namespace `service-interconnect`)
 
-Each spoke runs a Gateway API gateway that fronts all Industrial Edge services, providing a single entry point for Skupper to expose to the hub.
+| Listener | Port | Purpose |
+| --- | --- | --- |
+| `ie-gateway-east` | 8080 | Spoke-gateway traffic from east |
+| `ie-gateway-west` | 8080 | Spoke-gateway traffic from west |
+| `prometheus-east` | 9091 | Prometheus metrics from east |
+| `prometheus-west` | 9091 | Prometheus metrics from west |
+| `kafka-east-tst` | 9092 | Kafka bootstrap (dev-cluster) from east |
+| `kafka-west-tst` | 9092 | Kafka bootstrap (dev-cluster) from west |
 
-One Connector per spoke exposes the gateway instead of every microservice individually.
+### Spoke connectors
+
+| Connector | Exposes |
+| --- | --- |
+| `ie-gateway-<spoke>` | Local spoke-gateway |
+| `prometheus-<spoke>` | Nginx auth proxy → Thanos Querier |
+| `kafka-<spoke>-tst` | `dev-cluster-kafka-bootstrap` |
+| `kafka-<spoke>-stormshift` | `factory-cluster-kafka-bootstrap` |
+
+**Link establishment:** Hub `AccessGrant` generates URL, code, and CA. Spoke `AccessToken` redeems the grant over HTTPS, then establishes the inter-router link. Use the Skupper grant-server CA from `skupper-grant-server-ca` — not the OpenShift Ingress CA — or spokes fail with `x509: certificate signed by unknown authority`.
+
+```bash
+oc get secret skupper-grant-server-ca -n openshift-operators \
+  -o jsonpath='{.data.ca\.crt}' | base64 -d
+```
+
+Charts: `components/service-interconnect` (hub), `components/spoke-interconnect` (spokes).
+
+## Spoke gateway aggregation
+
+Each spoke runs a Gateway API gateway (`components/spoke-gateway`) that fronts all Industrial Edge services. Skupper exposes **one** gateway per spoke instead of every microservice individually.
 
 ## Multi-cluster observability pipeline
 
-Spoke Thanos Querier is reached through nginx auth-proxy Connectors; hub Grafana uses HTTP datasources without bearer tokens.
+Spoke Thanos Querier is reached through nginx auth-proxy Connectors. Hub Listeners `prometheus-east` and `prometheus-west` become Grafana HTTP datasources (no bearer token from hub).
 
 [![Observability pipeline](/images/hybrid-mesh-platform/arch-observability-pipeline.png)](/images/hybrid-mesh-platform/arch-observability-pipeline.png)
 
 ## Data flow (sensors to dashboard)
 
-Telemetry path on each spoke; MirrorMaker replicates to the hub-centralized MinIO data lake.
+On each spoke, telemetry flows from sensors through MQTT, Camel, and Kafka to dashboards. Strimzi MirrorMaker replicates factory topics toward the hub-centralized data lake (MinIO/S3 archiver on hub and spokes).
 
 ## Comparison with Red Hat Validated Patterns
 
-The [Multicloud GitOps](/patterns/multicloud-gitops) validated pattern demonstrates fleet GitOps with OpenShift GitOps and ACM patterns that resemble this repository's hub-push model: a declarative root Application, cluster grouping, and progressive rollout.
+The [Multicloud GitOps](/patterns/multicloud-gitops) validated pattern demonstrates fleet GitOps with OpenShift GitOps and ACM: declarative root Application, cluster grouping, and progressive rollout.
+
+**Hybrid Mesh Platform** extends that foundation with:
+
+- [Industrial Edge](/patterns/industrial-edge/) on **east** and **west** spokes (not duplicated here — see maintained pattern for OT/factory depth)
+- OpenShift Service Mesh 3 **ambient** mode (ztunnel L4, waypoints L7)
+- Connectivity Link for Gateway API ingress policy
+- Optional OpenShift AI (KServe) on spokes
+- ACS Central + SecuredCluster agents
+- Service Interconnect for cross-cluster service and metrics exposure
+
+The result is tuned for factory-style telemetry and east-west observability, not only infrastructure provisioning.
 
-This platform extends that idea with [Industrial Edge](/patterns/industrial-edge/) workloads deployed on multiple spokes, Service Mesh ambient, Connectivity Link, optional OpenShift AI, ACS depth, and Service Interconnect for cross-cluster service exposure — tuned for factory-style telemetry and east-west observability rather than only infrastructure provisioning.
+**Next →** [Getting Started](getting-started) to translate these diagrams into a live deployment, or [Hub Gateway](hub-gateway) for cross-cluster HTTP routing detail.