# dsx-ai-factory/nvcf architecture

> Architecture diagram of the GitHub repository dsx-ai-factory/nvcf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dsx-ai-factory/nvcf
- Repository: https://github.com/dsx-ai-factory/nvcf

## Overview

NVCF is a platform for deploying, managing, and invoking GPU workloads across clusters. A representative user workflow configures the CLI, creates and deploys a function, then sends an invocation through the invocation plane to a running workload. The broader architecture also includes control-plane lifecycle management, NVCA cluster integration, artifact registries, asynchronous tasks, and observability. The README supports the platform-level links; sampled source confirms selected LLM and registry behaviors, but most service internals were not inspected.

Main entry points: [`src/control-plane-services/cloud-functions/nvcf-core`](https://github.com/dsx-ai-factory/nvcf/tree/main/src/control-plane-services/cloud-functions/nvcf-core) (Control APIs), [`src/clis/nvcf-cli/cmd`](https://github.com/dsx-ai-factory/nvcf/tree/main/src/clis/nvcf-cli/cmd) (NVCF CLI), [`src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/service/function/FunctionLlmService.java`](https://github.com/dsx-ai-factory/nvcf/blob/main/src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/service/function/FunctionLlmService.java) (Function management), [`src/invocation-plane-services/http-invocation/crates/server/src/app.rs`](https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/http-invocation/crates/server/src/app.rs) (HTTP invocation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Clients and operations"]
  node_cli["NVCF CLI"]
  node_ui["NVCF UI"]
end

subgraph group_control["Control plane"]
  node_control_api["Control APIs"]
  node_function_service["Function management"]
  node_function_state[("Function records")]
  node_grpc_llm["LLM auth and routing"]
  node_icms["Cluster management"]
end

subgraph group_invoke["Invocation plane"]
  node_http_invoke["HTTP invocation<br/>[app.rs]"]
  node_grpc_proxy["gRPC proxy<br/>[main.go]"]
  node_llm_gateway["LLM gateway<br/>[server.go]"]
  node_rate_limiter["Rate limiting<br/>[main.go]"]
end

subgraph group_compute["Compute and observability"]
  node_nvca["GPU cluster agent"]
  node_shared_storage["Shared storage<br/>[sharedstorage.go]"]
  node_ess["Secrets agent"]
  node_otel["Telemetry collector<br/>[otelcollector.go]"]
  node_workers["Running workloads"]
  node_gpu_clusters["GPU clusters"]
end

subgraph group_platform["Platform services"]
  node_registry["Artifact registry access"]
  node_tasks["Task services"]
  node_artifact_store[("Artifact registries")]
end

node_user(("Platform user"))
node_client_apps(("Invocation clients"))

node_user -->|"configures and operates"| node_cli
node_user -.->|"manages workloads"| node_ui
node_cli -->|"manages functions"| node_control_api
node_ui -.->|"manages functions"| node_control_api
node_control_api -.->|"manages lifecycle"| node_function_service
node_function_service -.->|"persists state"| node_function_state
node_grpc_llm -->|"uses LLM config"| node_function_service
node_control_api -->|"coordinates clusters"| node_icms
node_client_apps -->|"sends requests"| node_http_invoke
node_client_apps -->|"sends gRPC"| node_grpc_proxy
node_http_invoke -->|"routes invocation"| node_workers
node_grpc_proxy -->|"routes invocation"| node_workers
node_llm_gateway -.->|"checks LLM auth"| node_grpc_llm
node_rate_limiter -.->|"limits requests"| node_http_invoke
node_nvca -->|"registers and manages"| node_gpu_clusters
node_workers -->|"runs on"| node_gpu_clusters
node_nvca -->|"reconciles storage"| node_shared_storage
node_ess -.->|"provides secrets"| node_workers
node_workers -.->|"emits telemetry"| node_otel
node_control_api -.->|"validates artifacts"| node_registry
node_registry -.->|"checks artifacts"| node_artifact_store
node_cli -->|"manages tasks"| node_tasks
node_control_api -.->|"supports workloads"| node_tasks

click node_cli "https://github.com/dsx-ai-factory/nvcf/tree/main/src/clis/nvcf-cli/cmd"
click node_ui "https://github.com/dsx-ai-factory/nvcf/tree/main/src/uis/nvcf-ui/ui/src"
click node_control_api "https://github.com/dsx-ai-factory/nvcf/tree/main/src/control-plane-services/cloud-functions/nvcf-core"
click node_function_service "https://github.com/dsx-ai-factory/nvcf/blob/main/src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/service/function/FunctionLlmService.java"
click node_function_state "https://github.com/dsx-ai-factory/nvcf/blob/main/src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/persistence/function/entity/FunctionEntity.java"
click node_grpc_llm "https://github.com/dsx-ai-factory/nvcf/blob/main/src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/grpc/GrpcLlmService.java"
click node_icms "https://github.com/dsx-ai-factory/nvcf/tree/main/src/control-plane-services/instance-cluster-management"
click node_http_invoke "https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/http-invocation/crates/server/src/app.rs"
click node_grpc_proxy "https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/grpc-proxy/main.go"
click node_llm_gateway "https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/llm-api-gateway/server/server.go"
click node_rate_limiter "https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/ratelimiter/cmd/main.go"
click node_nvca "https://github.com/dsx-ai-factory/nvcf/tree/main/src/compute-plane-services/nvca"
click node_shared_storage "https://github.com/dsx-ai-factory/nvcf/blob/main/src/compute-plane-services/nvca/pkg/storage/sharedstorage.go"
click node_ess "https://github.com/dsx-ai-factory/nvcf/tree/main/src/compute-plane-services/ess-agent"
click node_otel "https://github.com/dsx-ai-factory/nvcf/blob/main/src/compute-plane-services/byoo-otel-collector/internal/otelcollector/otelcollector.go"
click node_registry "https://github.com/dsx-ai-factory/nvcf/blob/main/src/libraries/java/nv-boot-parent/nv-boot-starter-registries/src/main/java/com/nvidia/boot/registries/service/registry/client/volcengine/VolcengineArtifactValidationService.java"
click node_tasks "https://github.com/dsx-ai-factory/nvcf/tree/main/src/control-plane-services/cloud-tasks"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_ui,node_user,node_client_apps toneBlue
class node_control_api,node_function_service,node_function_state,node_grpc_llm,node_icms toneAmber
class node_http_invoke,node_grpc_proxy,node_llm_gateway,node_rate_limiter toneMint
class node_nvca,node_shared_storage,node_ess,node_otel,node_workers,node_gpu_clusters toneRose
class node_registry,node_tasks,node_artifact_store toneIndigo
```

## Components

### Clients and operations

- [NVCF CLI](https://github.com/dsx-ai-factory/nvcf/tree/main/src/clis/nvcf-cli/cmd): `src/clis/nvcf-cli/cmd`
- [NVCF UI](https://github.com/dsx-ai-factory/nvcf/tree/main/src/uis/nvcf-ui/ui/src): `src/uis/nvcf-ui/ui/src`

### Control plane

- [Control APIs](https://github.com/dsx-ai-factory/nvcf/tree/main/src/control-plane-services/cloud-functions/nvcf-core): `src/control-plane-services/cloud-functions/nvcf-core`
- [Function management](https://github.com/dsx-ai-factory/nvcf/blob/main/src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/service/function/FunctionLlmService.java): `src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/service/function/FunctionLlmService.java`
- [Function records](https://github.com/dsx-ai-factory/nvcf/blob/main/src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/persistence/function/entity/FunctionEntity.java): `src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/persistence/function/entity/FunctionEntity.java`
- [LLM auth and routing](https://github.com/dsx-ai-factory/nvcf/blob/main/src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/grpc/GrpcLlmService.java): `src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/grpc/GrpcLlmService.java`
- [Cluster management](https://github.com/dsx-ai-factory/nvcf/tree/main/src/control-plane-services/instance-cluster-management): `src/control-plane-services/instance-cluster-management`

### Invocation plane

- [HTTP invocation](https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/http-invocation/crates/server/src/app.rs): `src/invocation-plane-services/http-invocation/crates/server/src/app.rs`
- [gRPC proxy](https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/grpc-proxy/main.go): `src/invocation-plane-services/grpc-proxy/main.go`
- [LLM gateway](https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/llm-api-gateway/server/server.go): `src/invocation-plane-services/llm-api-gateway/server/server.go`
- [Rate limiting](https://github.com/dsx-ai-factory/nvcf/blob/main/src/invocation-plane-services/ratelimiter/cmd/main.go): `src/invocation-plane-services/ratelimiter/cmd/main.go`

### Compute and observability

- [GPU cluster agent](https://github.com/dsx-ai-factory/nvcf/tree/main/src/compute-plane-services/nvca): `src/compute-plane-services/nvca`
- [Shared storage](https://github.com/dsx-ai-factory/nvcf/blob/main/src/compute-plane-services/nvca/pkg/storage/sharedstorage.go): `src/compute-plane-services/nvca/pkg/storage/sharedstorage.go`
- [Secrets agent](https://github.com/dsx-ai-factory/nvcf/tree/main/src/compute-plane-services/ess-agent): `src/compute-plane-services/ess-agent`
- [Telemetry collector](https://github.com/dsx-ai-factory/nvcf/blob/main/src/compute-plane-services/byoo-otel-collector/internal/otelcollector/otelcollector.go): `src/compute-plane-services/byoo-otel-collector/internal/otelcollector/otelcollector.go`
- **Running workloads**
- **GPU clusters**

### Platform services

- [Artifact registry access](https://github.com/dsx-ai-factory/nvcf/blob/main/src/libraries/java/nv-boot-parent/nv-boot-starter-registries/src/main/java/com/nvidia/boot/registries/service/registry/client/volcengine/VolcengineArtifactValidationService.java): `src/libraries/java/nv-boot-parent/nv-boot-starter-registries/src/main/java/com/nvidia/boot/registries/service/registry/client/volcengine/VolcengineArtifactValidationService.java`
- [Task services](https://github.com/dsx-ai-factory/nvcf/tree/main/src/control-plane-services/cloud-tasks): `src/control-plane-services/cloud-tasks`
- **Artifact registries**

### Other components

- **Platform user**
- **Invocation clients**

## Connections

- Platform user → NVCF CLI: configures and operates (evidence: `README.md`)
- Platform user → NVCF UI: manages workloads (evidence: `README.md`)
- NVCF CLI → Control APIs: manages functions (evidence: `README.md`)
- NVCF UI → Control APIs: manages functions (evidence: `README.md`)
- Control APIs → Function management: manages lifecycle (evidence: `README.md`)
- Function management → Function records: persists state (evidence: `README.md`)
- LLM auth and routing → Function management: uses LLM config (evidence: `src/control-plane-services/cloud-functions/nvcf-core/src/main/java/com/nvidia/nvcf/grpc/GrpcLlmService.java`)
- Control APIs → Cluster management: coordinates clusters (evidence: `README.md`)
- Invocation clients → HTTP invocation: sends requests (evidence: `README.md`)
- Invocation clients → gRPC proxy: sends gRPC (evidence: `README.md`)
- HTTP invocation → Running workloads: routes invocation (evidence: `README.md`)
- gRPC proxy → Running workloads: routes invocation (evidence: `README.md`)
- LLM gateway → LLM auth and routing: checks LLM auth (evidence: `README.md`)
- Rate limiting → HTTP invocation: limits requests (evidence: `README.md`)
- GPU cluster agent → GPU clusters: registers and manages (evidence: `README.md`)
- Running workloads → GPU clusters: runs on (evidence: `README.md`)
- GPU cluster agent → Shared storage: reconciles storage (evidence: `src/compute-plane-services/nvca/pkg/storage/sharedstorage.go`)
- Secrets agent → Running workloads: provides secrets (evidence: `README.md`)
- Running workloads → Telemetry collector: emits telemetry (evidence: `README.md`)
- Control APIs → Artifact registry access: validates artifacts (evidence: `src/libraries/java/nv-boot-parent/nv-boot-starter-registries/src/main/java/com/nvidia/boot/registries/service/registry/client/volcengine/VolcengineArtifactValidationService.java`)
- Artifact registry access → Artifact registries: checks artifacts (evidence: `README.md`)
- NVCF CLI → Task services: manages tasks (evidence: `README.md`)
- Control APIs → Task services: supports workloads (evidence: `README.md`)