# dmlc/xgboost architecture

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

- Interactive diagram: https://gitdiagram.com/dmlc/xgboost
- Repository: https://github.com/dmlc/xgboost

## Overview

XGBoost is a portable gradient-boosting library. The principal workflow is: a Python, JVM, R, or C user supplies tabular data; bindings create matrix representations; the learner computes objectives and metrics while fitting tree or linear boosters; the predictor returns scores, explanations, or serialized models. Distributed Dask/Spark execution, external-memory data, categorical features, checkpointing, and CPU/CUDA/SYCL execution are represented as branches. Some relationships rely on documented capabilities because only sampled source excerpts were available.

Main entry points: [`src/c_api/c_api.cc`](https://github.com/dmlc/xgboost/blob/master/src/c_api/c_api.cc) (C API), [`src/learner.cc`](https://github.com/dmlc/xgboost/blob/master/src/learner.cc) (Learner Orchestrator), [`include/xgboost/model.h`](https://github.com/dmlc/xgboost/blob/master/include/xgboost/model.h) (Model Persistence), [`src/data/adapter.cc`](https://github.com/dmlc/xgboost/blob/master/src/data/adapter.cc) (Data Adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bindings["Language Bindings"]
  node_python_api["Python API<br/>[core.py]"]
  node_jvm_api["JVM API<br/>[XGBoost.java]"]
  node_r_api["R API<br/>[xgboost_R.cc]"]
  node_c_api["C API<br/>[c_api.cc]"]
  node_dask_spark["Dask Spark Adapters<br/>[__init__.py]"]
  node_spark_adapter["Spark Adapter<br/>[estimator.py]"]
end

subgraph group_data["Data Layer"]
  node_data_api["Data Adapters<br/>[adapter.cc]"]
  node_dmatrix["DMatrix Storage<br/>[simple_dmatrix.cc]"]
  node_external_memory["External Memory"]
  node_categorical_data["Categorical Data<br/>[cat_container.cc]"]
end

subgraph group_training["Training Core"]
  node_learner["Learner Orchestrator<br/>[learner.cc]"]
  node_objectives["Objectives<br/>[objective.cc]"]
  node_metrics["Evaluation Metrics<br/>[metric.cc]"]
  node_boosters["Boosting Models<br/>[gbm.cc]"]
end

subgraph group_inference["Inference Models"]
  node_predictor["Predictor<br/>[predictor.cc]"]
  node_interpretability["SHAP Explanations<br/>[shap.cc]"]
  node_model_io["Model Persistence<br/>[model.h]"]
end

subgraph group_runtime["Scale Runtime"]
  node_collective["Distributed Collective<br/>[comm.cc]"]
  node_device_context["Device Context<br/>[context.cc]"]
  node_sycl_devices["SYCL Devices<br/>[device_manager.cc]"]
  node_checkpoint_manager["Checkpoint Manager"]
end

node_model_artifacts["Model Artifacts"]
node_python_user(("Python User"))
node_jvm_user(("JVM User"))
node_r_user(("R User"))
node_c_user(("C User"))
node_distributed_runtime["Distributed Runtime"]

node_python_user -->|"calls"| node_python_api
node_jvm_user -->|"calls"| node_jvm_api
node_r_user -->|"calls"| node_r_api
node_c_user -->|"calls"| node_c_api
node_dask_spark -.->|"orchestrates"| node_python_api
node_spark_adapter -.->|"orchestrates"| node_jvm_api
node_python_api -->|"calls"| node_c_api
node_jvm_api -->|"calls"| node_c_api
node_r_api -->|"calls"| node_c_api
node_c_api -->|"creates data"| node_data_api
node_data_api -->|"builds matrix"| node_dmatrix
node_data_api -.->|"streams pages"| node_external_memory
node_dmatrix -->|"stores categories"| node_categorical_data
node_c_api -->|"trains model"| node_learner
node_c_api -->|"requests scores"| node_predictor
node_learner -->|"computes gradients"| node_objectives
node_learner -->|"fits booster"| node_boosters
node_learner -->|"evaluates rounds"| node_metrics
node_learner -.->|"synchronizes"| node_collective
node_predictor -.->|"computes explanations"| node_interpretability
node_learner -->|"saves model"| node_model_io
node_model_io -->|"writes model"| node_model_artifacts
node_model_artifacts -->|"reads model"| node_model_io
node_checkpoint_manager -->|"loads checkpoints"| node_model_io
node_checkpoint_manager -->|"writes checkpoints"| node_model_artifacts
node_distributed_runtime -->|"provides ranks"| node_collective
node_device_context -.->|"selects queues"| node_sycl_devices

click node_python_api "https://github.com/dmlc/xgboost/blob/master/python-package/xgboost/core.py"
click node_jvm_api "https://github.com/dmlc/xgboost/blob/master/jvm-packages/xgboost4j/src/main/java/ml/dmlc/xgboost4j/java/XGBoost.java"
click node_r_api "https://github.com/dmlc/xgboost/blob/master/R-package/src/xgboost_R.cc"
click node_c_api "https://github.com/dmlc/xgboost/blob/master/src/c_api/c_api.cc"
click node_dask_spark "https://github.com/dmlc/xgboost/blob/master/python-package/xgboost/dask/__init__.py"
click node_spark_adapter "https://github.com/dmlc/xgboost/blob/master/python-package/xgboost/spark/estimator.py"
click node_data_api "https://github.com/dmlc/xgboost/blob/master/src/data/adapter.cc"
click node_dmatrix "https://github.com/dmlc/xgboost/blob/master/src/data/simple_dmatrix.cc"
click node_external_memory "https://github.com/dmlc/xgboost/blob/master/src/data/extmem_quantile_dmatrix.cc"
click node_categorical_data "https://github.com/dmlc/xgboost/blob/master/src/data/cat_container.cc"
click node_learner "https://github.com/dmlc/xgboost/blob/master/src/learner.cc"
click node_objectives "https://github.com/dmlc/xgboost/blob/master/src/objective/objective.cc"
click node_metrics "https://github.com/dmlc/xgboost/blob/master/src/metric/metric.cc"
click node_boosters "https://github.com/dmlc/xgboost/blob/master/src/gbm/gbm.cc"
click node_predictor "https://github.com/dmlc/xgboost/blob/master/src/predictor/predictor.cc"
click node_interpretability "https://github.com/dmlc/xgboost/blob/master/src/predictor/interpretability/shap.cc"
click node_model_io "https://github.com/dmlc/xgboost/blob/master/include/xgboost/model.h"
click node_collective "https://github.com/dmlc/xgboost/blob/master/src/collective/comm.cc"
click node_device_context "https://github.com/dmlc/xgboost/blob/master/src/context.cc"
click node_sycl_devices "https://github.com/dmlc/xgboost/blob/master/plugin/sycl/device_manager.cc"
click node_checkpoint_manager "https://github.com/dmlc/xgboost/blob/master/jvm-packages/xgboost4j/src/main/java/ml/dmlc/xgboost4j/java/ExternalCheckpointManager.java"

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_python_api,node_jvm_api,node_r_api,node_c_api,node_dask_spark,node_spark_adapter,node_python_user,node_jvm_user,node_r_user,node_c_user toneBlue
class node_data_api,node_dmatrix,node_external_memory,node_categorical_data toneAmber
class node_learner,node_objectives,node_metrics,node_boosters toneMint
class node_predictor,node_interpretability,node_model_io toneRose
class node_collective,node_device_context,node_sycl_devices,node_checkpoint_manager,node_model_artifacts,node_distributed_runtime toneIndigo
```

## Components

### Language Bindings

- [Python API](https://github.com/dmlc/xgboost/blob/master/python-package/xgboost/core.py): `python-package/xgboost/core.py`
- [JVM API](https://github.com/dmlc/xgboost/blob/master/jvm-packages/xgboost4j/src/main/java/ml/dmlc/xgboost4j/java/XGBoost.java): `jvm-packages/xgboost4j/src/main/java/ml/dmlc/xgboost4j/java/XGBoost.java`
- [R API](https://github.com/dmlc/xgboost/blob/master/R-package/src/xgboost_R.cc): `R-package/src/xgboost_R.cc`
- [C API](https://github.com/dmlc/xgboost/blob/master/src/c_api/c_api.cc): `src/c_api/c_api.cc`
- [Dask Spark Adapters](https://github.com/dmlc/xgboost/blob/master/python-package/xgboost/dask/__init__.py): `python-package/xgboost/dask/__init__.py`
- [Spark Adapter](https://github.com/dmlc/xgboost/blob/master/python-package/xgboost/spark/estimator.py): `python-package/xgboost/spark/estimator.py`

### Data Layer

- [Data Adapters](https://github.com/dmlc/xgboost/blob/master/src/data/adapter.cc): `src/data/adapter.cc`
- [DMatrix Storage](https://github.com/dmlc/xgboost/blob/master/src/data/simple_dmatrix.cc): `src/data/simple_dmatrix.cc`
- [External Memory](https://github.com/dmlc/xgboost/blob/master/src/data/extmem_quantile_dmatrix.cc): `src/data/extmem_quantile_dmatrix.cc`
- [Categorical Data](https://github.com/dmlc/xgboost/blob/master/src/data/cat_container.cc): `src/data/cat_container.cc`

### Training Core

- [Learner Orchestrator](https://github.com/dmlc/xgboost/blob/master/src/learner.cc): `src/learner.cc`
- [Objectives](https://github.com/dmlc/xgboost/blob/master/src/objective/objective.cc): `src/objective/objective.cc`
- [Evaluation Metrics](https://github.com/dmlc/xgboost/blob/master/src/metric/metric.cc): `src/metric/metric.cc`
- [Boosting Models](https://github.com/dmlc/xgboost/blob/master/src/gbm/gbm.cc): `src/gbm/gbm.cc`

### Inference Models

- [Predictor](https://github.com/dmlc/xgboost/blob/master/src/predictor/predictor.cc): `src/predictor/predictor.cc`
- [SHAP Explanations](https://github.com/dmlc/xgboost/blob/master/src/predictor/interpretability/shap.cc): `src/predictor/interpretability/shap.cc`
- [Model Persistence](https://github.com/dmlc/xgboost/blob/master/include/xgboost/model.h): `include/xgboost/model.h`

### Scale Runtime

- [Distributed Collective](https://github.com/dmlc/xgboost/blob/master/src/collective/comm.cc): `src/collective/comm.cc`
- [Device Context](https://github.com/dmlc/xgboost/blob/master/src/context.cc): `src/context.cc`
- [SYCL Devices](https://github.com/dmlc/xgboost/blob/master/plugin/sycl/device_manager.cc): `plugin/sycl/device_manager.cc`
- [Checkpoint Manager](https://github.com/dmlc/xgboost/blob/master/jvm-packages/xgboost4j/src/main/java/ml/dmlc/xgboost4j/java/ExternalCheckpointManager.java): `jvm-packages/xgboost4j/src/main/java/ml/dmlc/xgboost4j/java/ExternalCheckpointManager.java`

### Other components

- **Model Artifacts**
- **Python User**
- **JVM User**
- **R User**
- **C User**
- **Distributed Runtime**

## Connections

- Python User → Python API: calls
- JVM User → JVM API: calls
- R User → R API: calls
- C User → C API: calls
- Dask Spark Adapters → Python API: orchestrates
- Spark Adapter → JVM API: orchestrates
- Python API → C API: calls
- JVM API → C API: calls
- R API → C API: calls
- C API → Data Adapters: creates data
- Data Adapters → DMatrix Storage: builds matrix
- Data Adapters → External Memory: streams pages
- DMatrix Storage → Categorical Data: stores categories
- C API → Learner Orchestrator: trains model
- C API → Predictor: requests scores
- Learner Orchestrator → Objectives: computes gradients
- Learner Orchestrator → Boosting Models: fits booster
- Learner Orchestrator → Evaluation Metrics: evaluates rounds
- Learner Orchestrator → Distributed Collective: synchronizes
- Predictor → SHAP Explanations: computes explanations
- Learner Orchestrator → Model Persistence: saves model
- Model Persistence → Model Artifacts: writes model
- Model Artifacts → Model Persistence: reads model
- Checkpoint Manager → Model Persistence: loads checkpoints
- Checkpoint Manager → Model Artifacts: writes checkpoints
- Distributed Runtime → Distributed Collective: provides ranks
- Device Context → SYCL Devices: selects queues
