# nvidia/topograph architecture

> Architecture diagram of the GitHub repository nvidia/topograph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/topograph
- Repository: https://github.com/nvidia/topograph

## Overview

##### Project Type and Purpose
- Topograph is a network topology service, designed to provide physical cluster network topologies so that workload managers (like SLURM or Kubernetes environments) can perform network-aware scheduling.
- Its major purpose is to listen for incoming topology requests (via an API server), observe node changes (with a node observer in Kubernetes), fetch data from various cloud or bare-metal providers (via provider modules), and then convert or translate that information (via the engine) to the appropriate format for consumption.

##### Major Components & Their Roles (as seen in both the README and file structure)
- API Server – Listens for HTTP requests on a defined port and triggers provider operations when a topology generation request is received.
- Node Observer – Specifically included for Kubernetes deployments, it monitors node status changes and signals the API Server to initiate a topology configuration update.
- Provider – This component interacts with various Cloud Service Providers (like AWS, GCP, OCI, CoreWeave, or Bare Metal) to fetch raw topology data and convert it into an internal representation.
- Engine – Translates the internal representation into a final output expected by the workload scheduler (e.g., SLURM or Kubernetes ConfigMap).
- Additionally, note the presence of “cmd” directories for each main executable (node-observer, topograph, toposim) that launch these components, indicating execution entry points.
- Supporting Libraries, Modules, and Interactions: The extensive “pkg”, “internal”, and “protos” directories indicate how configuration, engine logic, provider interfaces, and network communication (including gRPC) are structured.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External client
    Client["Client/Cluster Environment"]:::external

    %% Main services
    node_api["API Server (HTTP endpoints)"]:::service
    node_observer["Node Observer (Kubernetes watch)"]:::service
    node_grpc["gRPC Communication (pkg/protos)"]:::protocol
    node_provider["Provider (CSP integration)"]:::service
    node_engine["Engine (Topology transformation)"]:::service

    %% Deployment & Configuration subgraph
    subgraph "Deployment & Configuration"
        configFile["Config File"]:::deployment
        helmObs["Helm Chart (Node Observer)"]:::deployment
        helmTopo["Helm Chart (Topograph)"]:::deployment
    end

    %% Data flow
    Client -->|"sendsRequest"| node_api
    node_observer -->|"notifies"| node_api
    node_api -->|"usesGRPC"| node_grpc
    node_grpc -->|"fetchesData"| node_provider
    node_provider -->|"sendsTopology"| node_engine
    node_engine -->|"responses"| Client

    %% Deployment links (dashed)
    configFile -.-> node_api
    configFile -.-> node_engine
    helmObs -.-> node_observer
    helmTopo -.-> node_api

    %% Click Events
    click node_api "https://github.com/nvidia/topograph/blob/main/cmd/topograph/main.go"
    click node_observer "https://github.com/nvidia/topograph/blob/main/cmd/node-observer/main.go"
    click node_provider "https://github.com/nvidia/topograph/tree/main/pkg/providers"
    click node_engine "https://github.com/nvidia/topograph/tree/main/pkg/engines"
    click node_grpc "https://github.com/nvidia/topograph/tree/main/pkg/protos"
    click configFile "https://github.com/nvidia/topograph/blob/main/config/topograph-config.yaml"
    click helmObs "https://github.com/nvidia/topograph/tree/main/charts/node-observer"
    click helmTopo "https://github.com/nvidia/topograph/tree/main/charts/topograph"

    %% Styles
    classDef external fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef service fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef protocol fill:#f94144,stroke:#333,stroke-width:2px;
    classDef deployment fill:#577590,stroke:#333,stroke-width:2px, color:#fff;
```
