docs(architecture): diagram and workflow text omit on-prem sources, the NFD engine, and node-data-broker relationships

[resker]

Summary

docs/architecture.md and its diagram (docs/assets/design.png) have drifted from the current architecture. The most consequential gap is that the Node Data Broker appears with no connections, which hides the relationship that explains why it exists — and why it needs elevated privileges for InfiniBand.

Specific issues

1. Node Data Broker is drawn unconnected. It has two real relationships: the infiniband-k8s provider execs ibnetdiscover inside the broker pod (pkg/providers/infiniband/k8s.go:48-57 → GetDaemonSetPods + ExecInPod, wired at provider_k8s.go:106), and the broker writes node annotations the provider consumes. Neither is shown, so the broker reads as decorative.

2. Observer and Broker boxes visually overlap in the rendered PNG.

3. Slinky is drawn but unconnected — no edge in or out, despite having its own engine.

4. Only a "CSP" cloud is shown as a topology source. On-prem sources are absent: NetQ, the InfiniBand fabric, and the GPU Operator's nvidia.com/gpu.clique labels (used by dra, and by infiniband-k8s with useGpuCliqueLabel). The prose has the same bias — "The Provider receives notifications and invokes CSP API to retrieve topology-related information" — which omits every on-prem path.

5. The NFD engine is missing. Added in #402 and documented at docs/overview.md:52 / docs/engines/nfd.md, but absent from the diagram.

6. The consumer layer flattens two different levels. Node labels, NFD custom resources, and the Slinky ConfigMap are all Kubernetes objects; only bare-metal Slurm sits outside Kubernetes. Drawing Slurm / Slinky / Kubernetes as peers obscures that Slinky runs on Kubernetes.

Proposed structure

Same structure as Mermaid, if it's easier to adapt:

flowchart TB
  subgraph CONSUMERS["Where topology is consumed"]
    subgraph BM["Bare metal / VM"]
      SLURM["Slurm<br/>topology.conf"]
    end
    subgraph K8SGRP["Kubernetes"]
      LABELS["Node labels<br/>network.topology.nvidia.com/*"]
      NFDCR["NFD custom resources<br/>NodeFeature / NodeFeatureGroup"]
      SLINKYCM["Slinky ConfigMap<br/>topology.conf for Slurm on Kubernetes"]
    end
  end
  subgraph TG["Topograph"]
    API["API server"]
    PROV["Provider"]
    ENG["Engine"]
    OBS["Node observer<br/>(K8s / Slinky only)"]
    NDB["Node data broker<br/>(K8s / Slinky only)"]
  end
  subgraph SRC["Topology sources"]
    CSP(["Cloud provider APIs<br/>aws · gcp · oci · nebius · nscale · lambdai"])
    GPUOP["GPU Operator node labels<br/>nvidia.com/gpu.clique · dra"]
    NETQ["NVIDIA NetQ<br/>netq"]
    IB["InfiniBand fabric<br/>infiniband-bm · infiniband-k8s"]
  end
  SLURM -->|"POST /v1/generate"| API
  OBS -->|"node / pod change"| API
  OBS -.->|"watches nodes / pods"| K8SGRP
  API --> PROV
  PROV -->|"topology graph"| ENG
  ENG --> SLURM
  ENG --> LABELS
  ENG --> NFDCR
  ENG --> SLINKYCM
  PROV -->|"exec ibnetdiscover"| NDB
  NDB -->|"node annotations"| PROV
  NDB -->|"queries fabric"| IB
  PROV -->|"queries"| CSP
  PROV -->|"queries"| NETQ
  GPUOP -->|"clique labels"| PROV

Loading

Suggested acceptance criteria

• Diagram shows the node-data-broker's ibnetdiscover exec path and annotation write-back
• No overlapping boxes; Slinky connected
• Topology sources include on-prem (NetQ, InfiniBand, GPU Operator labels) alongside cloud APIs
• NFD engine represented
• Consumer layer distinguishes Kubernetes objects from bare-metal Slurm
• architecture.md Workflow section no longer says the Provider only "invokes CSP API"