# sfdo-tooling/cumulusci architecture

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

- Interactive diagram: https://gitdiagram.com/sfdo-tooling/cumulusci
- Repository: https://github.com/sfdo-tooling/cumulusci

## Overview

CumulusCI is a Salesforce application-development automation platform. The principal workflow is to invoke configured tasks and flows from the CLI, resolve project and org configuration, and execute Salesforce setup, testing, data, or deployment actions. Separate capabilities include dependency management, metadata transformations, browser automation, and MetaDeploy delivery. Edges supported by the README are cited there; source excerpts are limited, so some internal runtime links are marked dashed and unverified rather than asserted as observed calls.

Main entry points: [`cumulusci/core/tasks.py`](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/tasks.py) (Task engine), [`cumulusci/cli/runtime.py`](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/cli/runtime.py) (CLI runtime), [`cumulusci/cli/cci.py`](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/cli/cci.py) (Command line), [`cumulusci/core/flowrunner.py`](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/flowrunner.py) (Flow runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Automation runtime"]
  node_cli["Command line<br/>[cci.py]"]
  node_cli_runtime["CLI runtime<br/>[runtime.py]"]
  node_flowrunner["Flow runner<br/>[flowrunner.py]"]
  node_task_engine["Task engine<br/>[tasks.py]"]
end

subgraph group_configuration["Project and org"]
  node_project_config["Project configuration<br/>[project_config.py]"]
  node_org_config["Org configuration<br/>[org_config.py]"]
  node_keychain[("Credential keychain")]
  node_oauth["OAuth client<br/>[client.py]"]
end

subgraph group_salesforce["Salesforce operations"]
  node_dependencies["Dependency resolver<br/>[resolvers.py]"]
  node_metadata_tasks["Metadata tasks"]
  node_metadata_api["Metadata API<br/>[metadata.py]"]
  node_metadata_transforms["Metadata transforms<br/>[transforms.py]"]
  node_package_tasks["Package operations"]
end

subgraph group_quality_data["Testing and data"]
  node_bulk_data["Bulk data tasks"]
  node_snowfakery["Synthetic data<br/>[snowfakery.py]"]
  node_robot["Browser automation"]
end

subgraph group_delivery["Distribution and delivery"]
  node_github_tasks["GitHub workflows"]
  node_metadeploy["MetaDeploy"]
end

node_developer(("Developer / admin"))
node_salesforce_org[("Salesforce org")]
node_ci(("CI system"))

node_developer -->|"invokes"| node_cli
node_cli -.->|"runs commands"| node_cli_runtime
node_cli_runtime -.->|"starts flows"| node_flowrunner
node_flowrunner -.->|"dispatches tasks"| node_task_engine
node_task_engine -->|"uses configuration"| node_project_config
node_task_engine -->|"uses org config"| node_org_config
node_cli_runtime -.->|"loads credentials"| node_keychain
node_keychain -.->|"supplies auth"| node_oauth
node_oauth -.->|"authenticates"| node_salesforce_org
node_org_config -->|"targets org"| node_salesforce_org
node_task_engine -->|"installs dependencies"| node_dependencies
node_task_engine -->|"runs metadata tasks"| node_metadata_tasks
node_metadata_tasks -.->|"deploys metadata"| node_metadata_api
node_metadata_transforms -->|"tailors metadata"| node_salesforce_org
node_task_engine -->|"runs deployment"| node_package_tasks
node_package_tasks -->|"installs or deploys"| node_salesforce_org
node_task_engine -->|"runs data tasks"| node_bulk_data
node_bulk_data -->|"loads datasets"| node_salesforce_org
node_snowfakery -->|"loads synthetic data"| node_salesforce_org
node_task_engine -->|"runs browser tests"| node_robot
node_ci -->|"runs automation"| node_cli
node_task_engine -.->|"runs release tasks"| node_github_tasks
node_task_engine -->|"exposes automation"| node_metadeploy

click node_cli "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/cli/cci.py"
click node_cli_runtime "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/cli/runtime.py"
click node_flowrunner "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/flowrunner.py"
click node_task_engine "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/tasks.py"
click node_project_config "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/config/project_config.py"
click node_org_config "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/config/org_config.py"
click node_keychain "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/keychain/base_project_keychain.py"
click node_oauth "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/oauth/client.py"
click node_dependencies "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/dependencies/resolvers.py"
click node_metadata_tasks "https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/tasks/metadata"
click node_metadata_api "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/salesforce_api/metadata.py"
click node_metadata_transforms "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/source_transforms/transforms.py"
click node_package_tasks "https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/tasks/salesforce"
click node_bulk_data "https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/tasks/bulkdata"
click node_snowfakery "https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/tasks/bulkdata/snowfakery.py"
click node_robot "https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/robotframework"
click node_github_tasks "https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/tasks/github"
click node_metadeploy "https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/core/metadeploy"

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_cli_runtime,node_flowrunner,node_task_engine toneBlue
class node_project_config,node_org_config,node_keychain,node_oauth,node_salesforce_org toneAmber
class node_dependencies,node_metadata_tasks,node_metadata_api,node_metadata_transforms,node_package_tasks toneMint
class node_bulk_data,node_snowfakery,node_robot toneRose
class node_github_tasks,node_metadeploy,node_developer,node_ci toneIndigo
```

## Components

### Automation runtime

- [Command line](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/cli/cci.py): `cumulusci/cli/cci.py`
- [CLI runtime](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/cli/runtime.py): `cumulusci/cli/runtime.py`
- [Flow runner](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/flowrunner.py): `cumulusci/core/flowrunner.py`
- [Task engine](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/tasks.py): `cumulusci/core/tasks.py`

### Project and org

- [Project configuration](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/config/project_config.py): `cumulusci/core/config/project_config.py`
- [Org configuration](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/config/org_config.py): `cumulusci/core/config/org_config.py`
- [Credential keychain](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/keychain/base_project_keychain.py): `cumulusci/core/keychain/base_project_keychain.py`
- [OAuth client](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/oauth/client.py): `cumulusci/oauth/client.py`

### Salesforce operations

- [Dependency resolver](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/dependencies/resolvers.py): `cumulusci/core/dependencies/resolvers.py`
- [Metadata tasks](https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/tasks/metadata): `cumulusci/tasks/metadata`
- [Metadata API](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/salesforce_api/metadata.py): `cumulusci/salesforce_api/metadata.py`
- [Metadata transforms](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/core/source_transforms/transforms.py): `cumulusci/core/source_transforms/transforms.py`
- [Package operations](https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/tasks/salesforce): `cumulusci/tasks/salesforce`

### Testing and data

- [Bulk data tasks](https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/tasks/bulkdata): `cumulusci/tasks/bulkdata`
- [Synthetic data](https://github.com/sfdo-tooling/cumulusci/blob/main/cumulusci/tasks/bulkdata/snowfakery.py): `cumulusci/tasks/bulkdata/snowfakery.py`
- [Browser automation](https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/robotframework): `cumulusci/robotframework`

### Distribution and delivery

- [GitHub workflows](https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/tasks/github): `cumulusci/tasks/github`
- [MetaDeploy](https://github.com/sfdo-tooling/cumulusci/tree/main/cumulusci/core/metadeploy): `cumulusci/core/metadeploy`

### Other components

- **Developer / admin**
- **Salesforce org**
- **CI system**

## Connections

- Developer / admin → Command line: invokes
- Command line → CLI runtime: runs commands
- CLI runtime → Flow runner: starts flows
- Flow runner → Task engine: dispatches tasks (evidence: `cumulusci/core/tasks.py`)
- Task engine → Project configuration: uses configuration (evidence: `cumulusci/core/tasks.py`)
- Task engine → Org configuration: uses org config (evidence: `cumulusci/core/tasks.py`)
- CLI runtime → Credential keychain: loads credentials
- Credential keychain → OAuth client: supplies auth
- OAuth client → Salesforce org: authenticates
- Org configuration → Salesforce org: targets org
- Task engine → Dependency resolver: installs dependencies
- Task engine → Metadata tasks: runs metadata tasks
- Metadata tasks → Metadata API: deploys metadata
- Metadata transforms → Salesforce org: tailors metadata
- Task engine → Package operations: runs deployment (evidence: `cumulusci/tasks/salesforce/BaseSalesforceApiTask.py`)
- Package operations → Salesforce org: installs or deploys
- Task engine → Bulk data tasks: runs data tasks
- Bulk data tasks → Salesforce org: loads datasets
- Synthetic data → Salesforce org: loads synthetic data
- Task engine → Browser automation: runs browser tests
- CI system → Command line: runs automation
- Task engine → GitHub workflows: runs release tasks
- Task engine → MetaDeploy: exposes automation