# nvidia/cudf-spark architecture

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

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

## Overview

The repository is NVIDIA’s cuDF plugin for Apache Spark: Spark workloads are accelerated on GPUs while aiming for Spark-compatible results. The main runtime story is Spark invoking the plugin, which initializes GPU resources and provides an optimized shuffle manager; Delta Lake support extends this to table operations and transaction-aware writes. The tree documents broad Delta capabilities, but the supplied source excerpts mainly cover shuffle, resource management, and compatibility shims, so detailed wiring among Delta command implementations is not asserted.

Main entry points: [`delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuOptimisticTransaction.scala`](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuOptimisticTransaction.scala) (Transactions), [`sql-plugin/src/main/scala/org/apache/spark/sql/rapids/RapidsShuffleInternalManagerBase.scala`](https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/org/apache/spark/sql/rapids/RapidsShuffleInternalManagerBase.scala) (Shuffle manager), [`delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuDeleteCommand.scala`](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuDeleteCommand.scala) (DML commands), [`delta-lake/common/src/main/delta-40x-41x/scala/org/apache/spark/sql/delta/rapids/GpuMergeIntoCommand.scala`](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-41x/scala/org/apache/spark/sql/delta/rapids/GpuMergeIntoCommand.scala) (Merge commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Spark runtime"]
  node_plugin["GPU acceleration"]
  node_spj["Partition joins"]
end

subgraph group_gpu["GPU resources"]
  node_device["GPU manager"]
end

subgraph group_shuffle["Shuffle transport"]
  node_shuffleproxy["Shuffle proxy"]
  node_shuffleimpl["Shuffle manager"]
  node_shuffleversion["Version manager"]
  node_bounce["Bounce buffers"]
  node_traffic["Async throttling"]
end

subgraph group_delta["Delta Lake"]
  node_provider["Delta provider"]
  node_catalog["Delta catalog"]
  node_dml["DML commands"]
  node_merge["Merge commands"]
  node_optimize["Table optimize"]
  node_write["Delta writes"]
  node_transaction["Transactions"]
  node_vectors[("Deletion vectors")]
  node_cdf["Change feeds"]
  node_autocompact["Auto compact"]
  node_identity["Identity columns"]
end

node_spark(("Spark jobs"))
node_cudf["cuDF GPU"]
node_deltauser(("Delta operations"))

node_spark -->|"runs accelerated jobs"| node_plugin
node_plugin -->|"initializes resources"| node_device
node_device -->|"initializes GPU memory"| node_cudf
node_spark -->|"selects manager"| node_shuffleversion
node_shuffleversion -->|"extends proxy"| node_shuffleproxy
node_shuffleproxy -->|"loads and delegates"| node_shuffleimpl
node_shuffleimpl -->|"uses buffers"| node_bounce
node_shuffleimpl -->|"throttles async I/O"| node_traffic
node_spark -->|"uses join compatibility"| node_spj
node_deltauser -->|"requests table operations"| node_provider
node_provider -->|"provides catalog integration"| node_catalog
node_deltauser -->|"requests delete or update"| node_dml
node_deltauser -->|"requests merge"| node_merge
node_deltauser -->|"requests optimize"| node_optimize
node_deltauser -->|"requests table write"| node_write
node_write -->|"uses transaction"| node_transaction
node_dml -->|"uses transaction"| node_transaction
node_merge -->|"uses transaction"| node_transaction
node_optimize -->|"uses transaction"| node_transaction
node_dml -.->|"supports row deletion"| node_vectors
node_merge -.->|"supports row deletion"| node_vectors
node_deltauser -.->|"queries change feeds"| node_cdf
node_deltauser -.->|"enables compaction"| node_autocompact
node_write -.->|"supports identity columns"| node_identity

click node_device "https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/com/nvidia/spark/rapids/GpuDeviceManager.scala"
click node_shuffleproxy "https://github.com/nvidia/cudf-spark/blob/main/sql-plugin-api/src/main/scala/org/apache/spark/sql/rapids/ProxyRapidsShuffleInternalManagerBase.scala"
click node_shuffleimpl "https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/org/apache/spark/sql/rapids/RapidsShuffleInternalManagerBase.scala"
click node_shuffleversion "https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/spark330/scala/com/nvidia/spark/rapids/RapidsShuffleManager.scala"
click node_bounce "https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/com/nvidia/spark/rapids/shuffle/BounceBufferManager.scala"
click node_traffic "https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/com/nvidia/spark/rapids/io/async/TrafficController.scala"
click node_spj "https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/spark400/scala/com/nvidia/spark/rapids/shims/StoragePartitionJoinShims.scala"
click node_provider "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-42x/scala/com/nvidia/spark/rapids/delta/common/DeltaProviderBase.scala"
click node_catalog "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuDeltaCatalog4x.scala"
click node_dml "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuDeleteCommand.scala"
click node_merge "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-41x/scala/org/apache/spark/sql/delta/rapids/GpuMergeIntoCommand.scala"
click node_optimize "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/rapids/GpuOptimizeTableCommand.scala"
click node_write "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuWriteIntoDeltaBase.scala"
click node_transaction "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuOptimisticTransaction.scala"
click node_vectors "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/deletionvectors/RapidsDeletionVectorStore.scala"
click node_cdf "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-41x/scala/com/nvidia/spark/rapids/delta/common/DeltaCDFRelationStrategy.scala"
click node_autocompact "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/hooks/GpuAutoCompact.scala"
click node_identity "https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-io/scala/org/apache/spark/sql/rapids/delta/GpuIdentityColumn.scala"

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_plugin,node_spj toneBlue
class node_device toneAmber
class node_shuffleproxy,node_shuffleimpl,node_shuffleversion,node_bounce,node_traffic toneMint
class node_provider,node_catalog,node_dml,node_merge,node_optimize,node_write,node_transaction,node_vectors,node_cdf,node_autocompact,node_identity toneRose
class node_spark,node_cudf,node_deltauser toneIndigo
```

## Components

### Spark runtime

- **GPU acceleration**
- [Partition joins](https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/spark400/scala/com/nvidia/spark/rapids/shims/StoragePartitionJoinShims.scala): `sql-plugin/src/main/spark400/scala/com/nvidia/spark/rapids/shims/StoragePartitionJoinShims.scala`

### GPU resources

- [GPU manager](https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/com/nvidia/spark/rapids/GpuDeviceManager.scala): `sql-plugin/src/main/scala/com/nvidia/spark/rapids/GpuDeviceManager.scala`

### Shuffle transport

- [Shuffle proxy](https://github.com/nvidia/cudf-spark/blob/main/sql-plugin-api/src/main/scala/org/apache/spark/sql/rapids/ProxyRapidsShuffleInternalManagerBase.scala): `sql-plugin-api/src/main/scala/org/apache/spark/sql/rapids/ProxyRapidsShuffleInternalManagerBase.scala`
- [Shuffle manager](https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/org/apache/spark/sql/rapids/RapidsShuffleInternalManagerBase.scala): `sql-plugin/src/main/scala/org/apache/spark/sql/rapids/RapidsShuffleInternalManagerBase.scala`
- [Version manager](https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/spark330/scala/com/nvidia/spark/rapids/RapidsShuffleManager.scala): `sql-plugin/src/main/spark330/scala/com/nvidia/spark/rapids/RapidsShuffleManager.scala`
- [Bounce buffers](https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/com/nvidia/spark/rapids/shuffle/BounceBufferManager.scala): `sql-plugin/src/main/scala/com/nvidia/spark/rapids/shuffle/BounceBufferManager.scala`
- [Async throttling](https://github.com/nvidia/cudf-spark/blob/main/sql-plugin/src/main/scala/com/nvidia/spark/rapids/io/async/TrafficController.scala): `sql-plugin/src/main/scala/com/nvidia/spark/rapids/io/async/TrafficController.scala`

### Delta Lake

- [Delta provider](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-42x/scala/com/nvidia/spark/rapids/delta/common/DeltaProviderBase.scala): `delta-lake/common/src/main/delta-33x-42x/scala/com/nvidia/spark/rapids/delta/common/DeltaProviderBase.scala`
- [Delta catalog](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuDeltaCatalog4x.scala): `delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuDeltaCatalog4x.scala`
- [DML commands](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuDeleteCommand.scala): `delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuDeleteCommand.scala`
- [Merge commands](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-41x/scala/org/apache/spark/sql/delta/rapids/GpuMergeIntoCommand.scala): `delta-lake/common/src/main/delta-40x-41x/scala/org/apache/spark/sql/delta/rapids/GpuMergeIntoCommand.scala`
- [Table optimize](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/rapids/GpuOptimizeTableCommand.scala): `delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/rapids/GpuOptimizeTableCommand.scala`
- [Delta writes](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuWriteIntoDeltaBase.scala): `delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuWriteIntoDeltaBase.scala`
- [Transactions](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuOptimisticTransaction.scala): `delta-lake/common/src/main/delta-40x-42x/scala/org/apache/spark/sql/delta/rapids/GpuOptimisticTransaction.scala`
- [Deletion vectors](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/deletionvectors/RapidsDeletionVectorStore.scala): `delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/deletionvectors/RapidsDeletionVectorStore.scala`
- [Change feeds](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-41x/scala/com/nvidia/spark/rapids/delta/common/DeltaCDFRelationStrategy.scala): `delta-lake/common/src/main/delta-33x-41x/scala/com/nvidia/spark/rapids/delta/common/DeltaCDFRelationStrategy.scala`
- [Auto compact](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/hooks/GpuAutoCompact.scala): `delta-lake/common/src/main/delta-33x-42x/scala/org/apache/spark/sql/delta/hooks/GpuAutoCompact.scala`
- [Identity columns](https://github.com/nvidia/cudf-spark/blob/main/delta-lake/common/src/main/delta-io/scala/org/apache/spark/sql/rapids/delta/GpuIdentityColumn.scala): `delta-lake/common/src/main/delta-io/scala/org/apache/spark/sql/rapids/delta/GpuIdentityColumn.scala`

### Other components

- **Spark jobs**
- **cuDF GPU**
- **Delta operations**

## Connections

- Spark jobs → GPU acceleration: runs accelerated jobs
- GPU acceleration → GPU manager: initializes resources
- GPU manager → cuDF GPU: initializes GPU memory
- Spark jobs → Version manager: selects manager
- Version manager → Shuffle proxy: extends proxy
- Shuffle proxy → Shuffle manager: loads and delegates
- Shuffle manager → Bounce buffers: uses buffers
- Shuffle manager → Async throttling: throttles async I/O
- Spark jobs → Partition joins: uses join compatibility
- Delta operations → Delta provider: requests table operations
- Delta provider → Delta catalog: provides catalog integration
- Delta operations → DML commands: requests delete or update
- Delta operations → Merge commands: requests merge
- Delta operations → Table optimize: requests optimize
- Delta operations → Delta writes: requests table write
- Delta writes → Transactions: uses transaction
- DML commands → Transactions: uses transaction
- Merge commands → Transactions: uses transaction
- Table optimize → Transactions: uses transaction
- DML commands → Deletion vectors: supports row deletion
- Merge commands → Deletion vectors: supports row deletion
- Delta operations → Change feeds: queries change feeds
- Delta operations → Auto compact: enables compaction
- Delta writes → Identity columns: supports identity columns