# kubeflow/sdk architecture

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

- Interactive diagram: https://gitdiagram.com/kubeflow/sdk
- Repository: https://github.com/kubeflow/sdk

## Overview

##### Project Type and Purpose
- **Type**: Open-source Python SDK library.
- **Purpose**: Provide a unified Python API (TrainerClient/CustomTrainer) to submit and manage ML training jobs across multiple Kubeflow backends (local and Kubernetes), abstracting away infra complexity.

##### File Structure
- **Top-level files**: pyproject.toml, Makefile, CI configs in `.github/workflows/`, docs/, scripts/, kubeflow/ package.
- **Core package** `kubeflow/trainer`:
- `api/`: public client interface (`trainer_client.py`)
- `backends/`: pluggable executor implementations
– `kubernetes/backend.py` + types
– `localprocess/backend.py` + job launcher, utils
- `types/`: data models for Trainer, Runtime, Job specs
- `constants/`: shared constants
- `utils/`: helper functions (serialization, logging)
- **Docs & Proposals**: design discussions, local execution proposal.
- **CI/CD**: tests (unit, e2e), release workflows.

##### Key Insights from README
- Public API entry point: `TrainerClient().train(...)`
- Supports multiple “runtimes” (e.g., torch-distributed) via `get_runtime`
- Local development & Kubernetes supported
- Aim: unify interactions with various Kubeflow components (Trainer, Katib, Pipelines planned)

##### Components & Interactions
a. Main Components
1. **Client Application** (user’s Python script)
2. **Kubeflow SDK**
- **API Layer**: TrainerClient, CustomTrainer
- **Core Models**: types (JobSpec, RuntimeSpec)
- **Backends**:
– **LocalProcess Backend**: spawns OS processes
– **Kubernetes Backend**: calls Kubernetes API to create TrainingJob CRDs
- **Utils & Constants**
3. **External Services**
- **Kubernetes Cluster** (API server, control plane)
- **Container Registry** (for Docker images)
- **Logging/Monitoring** (e.g., Kubernetes logs)
b. Relationships & Data Flow
2. API → Core Models (builds JobSpec)
3. API → Backend Router (chooses local vs. k8s)
4. Local Backend → OS Processes → STDOUT/STDERR → SDK logs
5. Kubernetes Backend → kube-api server → create Job CRD → Worker Pods
6. Kubernetes Backend ← Pod status & logs ← SDK → Client app
c. Architectural Patterns / Principles
- **Adapter/Strategy Pattern**: pluggable backends implementing same interface (base.py)
- **Facade Pattern**: TrainerClient simplifies multiple subsystems
- **Modular Design**: clear separation into api, backends, types, utils
d. Key Technologies & Frameworks
- Python 3.8+ (PEP 621 via pyproject.toml)
- Kubernetes Python client
- PyPI packaging
- CI via GitHub Actions
- Local process management (multiprocessing, subprocess)

##### Detailed Breakdown to Capture
- `api` layer and its public methods
- Distinguish between two backend implementations under `backends/`
- Type/data flow through `types/`
- `utils/` as a shared component feeding into both backends

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    ClientApp["User Python Script"]:::external

    %% SDK Layer
    subgraph "Kubeflow SDK"
        subgraph "API Layer"
            TrainerClient["TrainerClient"]:::internal
        end
        subgraph "Core Models"
            JobSpec["JobSpec, RuntimeSpec"]:::data
        end
        subgraph "Backend Interface"
            Base["BackendBase"]:::internal
        end
        subgraph "Backend Implementations"
            LocalBackend["LocalProcessBackend"]:::internal
            KubeBackend["KubernetesBackend"]:::internal
        end
        subgraph "Utils & Constants"
            Utils["utils"]:::internal
            Const["constants"]:::internal
        end
    end

    %% Local Backend Details
    subgraph "Local Backend Details"
        JobLauncher["JobLauncher"]:::internal
        LocalUtils["localprocess utils"]:::internal
        LocalConst["localprocess constants"]:::internal
    end

    %% External Services
    subgraph "External Services"
        KubeAPI["Kubernetes API"]:::external
        ContainerReg["Container Registry"]:::external
        Logs["Logging/Monitoring"]:::external
    end

    %% Developer Resources
    subgraph "Developer Resources"
        Docs["Local Execution Proposal"]:::external
        CI["CI/CD Workflows"]:::external
        Config["pyproject.toml & Makefile"]:::external
    end

    %% Connections
    ClientApp -->|"calls train()"| TrainerClient
    TrainerClient -->|"builds spec"| JobSpec
    TrainerClient -->|"selects backend"| Base
    Base -->|implements| LocalBackend
    Base -->|implements| KubeBackend
    LocalBackend -->|"launch job"| JobLauncher
    LocalBackend -->|"uses utils"| LocalUtils
    LocalBackend -->|"uses constants"| LocalConst
    LocalBackend -->|"spawn OS process"| Logs
    KubeBackend -->|"pull image"| ContainerReg
    KubeBackend -->|"create CRD"| KubeAPI
    KubeAPI -->|"pod logs"| KubeBackend
    KubeBackend -->|"fetch logs"| Logs
    Utils --> LocalBackend
    Utils --> KubeBackend
    Const --> LocalBackend
    Const --> KubeBackend

    %% Developer Resources connections
    Docs --> TrainerClient
    CI --> Utils
    Config --> Utils

    %% Click Events
    click TrainerClient "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/api/trainer_client.py"
    click Base "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/backends/base.py"
    click KubeBackend "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/backends/kubernetes/backend.py"
    click LocalBackend "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/backends/localprocess/backend.py"
    click JobLauncher "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/backends/localprocess/job.py"
    click LocalUtils "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/backends/localprocess/utils.py"
    click LocalConst "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/backends/localprocess/constants.py"
    click JobSpec "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/types/types.py"
    click Const "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/constants/constants.py"
    click Utils "https://github.com/kubeflow/sdk/blob/main/kubeflow/trainer/utils/utils.py"
    click Docs "https://github.com/kubeflow/sdk/blob/main/docs/proposals/2-trainer-local-execution/README.md"
    click CI "https://github.com/kubeflow/sdk/blob/main/.github/workflows/test-python.yaml"
    click CI "https://github.com/kubeflow/sdk/blob/main/.github/workflows/test-e2e.yaml"
    click CI "https://github.com/kubeflow/sdk/blob/main/.github/workflows/release.yml"
    click Config "https://github.com/kubeflow/sdk/blob/main/pyproject.toml"
    click Config "https://github.com/kubeflow/sdk/tree/main/Makefile"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px
    classDef external fill:#D5F5E3,stroke:#145A32,stroke-width:1px
    classDef data fill:#FDEBD0,stroke:#B9770E,stroke-width:1px
```
