# cartography-cncf/cartography architecture

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

- Interactive diagram: https://gitdiagram.com/cartography-cncf/cartography
- Repository: https://github.com/cartography-cncf/cartography
- Video tour (about a minute): https://gitdiagram.com/cartography-cncf/cartography/video

## Overview

Cartography collects infrastructure and identity assets from many platforms, turns them into related graph records, and writes them to Neo4j. The main user workflow is to run the CLI with selected modules and credentials, sync the chosen sources, then query the graph or run security rules. The repository also contains analysis and drift-detection capabilities. Provider coverage is much broader than the sampled source; those branches are represented at subsystem level, and the documented workflow and source-index references support the connections shown.

Main entry points: [`cartography/intel`](https://github.com/cartography-cncf/cartography/tree/master/cartography/intel) (Transform and Load), [`cartography/models/core/nodes.py`](https://github.com/cartography-cncf/cartography/blob/master/cartography/models/core/nodes.py) (Graph Schemas), [`cartography/rules/cli.py`](https://github.com/cartography-cncf/cartography/blob/master/cartography/rules/cli.py) (Rules CLI), [`cartography/driftdetect/cli.py`](https://github.com/cartography-cncf/cartography/blob/master/cartography/driftdetect/cli.py) (Drift CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Collection and Sync"]
  node_cli["Cartography CLI<br/>[cli.py]"]
  node_sync["Sync Orchestrator<br/>[sync.py]"]
  node_intel["Provider Modules"]
  node_cloud_apis{{"Provider APIs"}}
  node_transform["Transform and Load"]
end

subgraph group_graph["Graph Storage"]
  node_tx["Neo4j Transactions<br/>[tx.py]"]
  node_job["Graph Jobs<br/>[job.py]"]
  node_models["Graph Schemas<br/>[nodes.py]"]
  node_relationships["Relationship Schemas<br/>[relationships.py]"]
  node_ontology["Ontology Mapping<br/>[labels.py]"]
  node_neo4j[("Neo4j")]
end

subgraph group_security["Analysis and Security"]
  node_analysis["Graph Analysis"]
  node_rules_cli["Rules CLI<br/>[cli.py]"]
  node_rules["Security Rules"]
  node_rule_model["Rule Specification<br/>[model.py]"]
end

subgraph group_drift["Drift Detection"]
  node_drift_cli["Drift CLI<br/>[cli.py]"]
  node_drift_states["State Collection<br/>[get_states.py]"]
  node_drift_storage[("Drift Storage<br/>[storage.py]")]
end

node_operator(("Operator"))

node_operator -->|"runs sync"| node_cli
node_cli -.->|"starts sync"| node_sync
node_sync -.->|"selects modules"| node_intel
node_intel -.->|"fetches assets"| node_cloud_apis
node_intel -->|"transforms assets"| node_transform
node_transform -->|"runs graph jobs"| node_job
node_transform -->|"loads schemas"| node_models
node_transform -->|"writes records"| node_tx
node_job -.->|"executes queries"| node_neo4j
node_tx -.->|"writes graph"| node_neo4j
node_models -->|"defines links"| node_relationships
node_models -->|"adds labels"| node_ontology
node_operator -->|"runs rules"| node_rules_cli
node_rules_cli -.->|"selects rules"| node_rules
node_rules -->|"uses definitions"| node_rule_model
node_rules_cli -->|"queries graph"| node_neo4j
node_operator -.->|"invokes analysis"| node_analysis
node_operator -.->|"runs drift checks"| node_drift_cli
node_drift_cli -.->|"collects states"| node_drift_states
node_drift_cli -.->|"stores states"| node_drift_storage

click node_cli "https://github.com/cartography-cncf/cartography/blob/master/cartography/cli.py"
click node_sync "https://github.com/cartography-cncf/cartography/blob/master/cartography/sync.py"
click node_intel "https://github.com/cartography-cncf/cartography/tree/master/cartography/intel"
click node_transform "https://github.com/cartography-cncf/cartography/tree/master/cartography/intel"
click node_tx "https://github.com/cartography-cncf/cartography/blob/master/cartography/client/core/tx.py"
click node_job "https://github.com/cartography-cncf/cartography/blob/master/cartography/graph/job.py"
click node_models "https://github.com/cartography-cncf/cartography/blob/master/cartography/models/core/nodes.py"
click node_relationships "https://github.com/cartography-cncf/cartography/blob/master/cartography/models/core/relationships.py"
click node_ontology "https://github.com/cartography-cncf/cartography/blob/master/cartography/models/ontology/labels.py"
click node_analysis "https://github.com/cartography-cncf/cartography/tree/master/cartography/analysis"
click node_rules_cli "https://github.com/cartography-cncf/cartography/blob/master/cartography/rules/cli.py"
click node_rules "https://github.com/cartography-cncf/cartography/tree/master/cartography/rules/data/rules"
click node_rule_model "https://github.com/cartography-cncf/cartography/blob/master/cartography/rules/spec/model.py"
click node_drift_cli "https://github.com/cartography-cncf/cartography/blob/master/cartography/driftdetect/cli.py"
click node_drift_states "https://github.com/cartography-cncf/cartography/blob/master/cartography/driftdetect/get_states.py"
click node_drift_storage "https://github.com/cartography-cncf/cartography/blob/master/cartography/driftdetect/storage.py"

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_sync,node_intel,node_cloud_apis,node_transform toneBlue
class node_tx,node_job,node_models,node_relationships,node_ontology,node_neo4j toneAmber
class node_analysis,node_rules_cli,node_rules,node_rule_model toneMint
class node_drift_cli,node_drift_states,node_drift_storage toneRose
class node_operator toneIndigo
```

## Components

### Collection and Sync

- [Cartography CLI](https://github.com/cartography-cncf/cartography/blob/master/cartography/cli.py): `cartography/cli.py`
- [Sync Orchestrator](https://github.com/cartography-cncf/cartography/blob/master/cartography/sync.py): `cartography/sync.py`
- [Provider Modules](https://github.com/cartography-cncf/cartography/tree/master/cartography/intel): `cartography/intel`
- **Provider APIs**
- [Transform and Load](https://github.com/cartography-cncf/cartography/tree/master/cartography/intel): `cartography/intel`

### Graph Storage

- [Neo4j Transactions](https://github.com/cartography-cncf/cartography/blob/master/cartography/client/core/tx.py): `cartography/client/core/tx.py`
- [Graph Jobs](https://github.com/cartography-cncf/cartography/blob/master/cartography/graph/job.py): `cartography/graph/job.py`
- [Graph Schemas](https://github.com/cartography-cncf/cartography/blob/master/cartography/models/core/nodes.py): `cartography/models/core/nodes.py`
- [Relationship Schemas](https://github.com/cartography-cncf/cartography/blob/master/cartography/models/core/relationships.py): `cartography/models/core/relationships.py`
- [Ontology Mapping](https://github.com/cartography-cncf/cartography/blob/master/cartography/models/ontology/labels.py): `cartography/models/ontology/labels.py`
- **Neo4j**

### Analysis and Security

- [Graph Analysis](https://github.com/cartography-cncf/cartography/tree/master/cartography/analysis): `cartography/analysis`
- [Rules CLI](https://github.com/cartography-cncf/cartography/blob/master/cartography/rules/cli.py): `cartography/rules/cli.py`
- [Security Rules](https://github.com/cartography-cncf/cartography/tree/master/cartography/rules/data/rules): `cartography/rules/data/rules`
- [Rule Specification](https://github.com/cartography-cncf/cartography/blob/master/cartography/rules/spec/model.py): `cartography/rules/spec/model.py`

### Drift Detection

- [Drift CLI](https://github.com/cartography-cncf/cartography/blob/master/cartography/driftdetect/cli.py): `cartography/driftdetect/cli.py`
- [State Collection](https://github.com/cartography-cncf/cartography/blob/master/cartography/driftdetect/get_states.py): `cartography/driftdetect/get_states.py`
- [Drift Storage](https://github.com/cartography-cncf/cartography/blob/master/cartography/driftdetect/storage.py): `cartography/driftdetect/storage.py`

### Other components

- **Operator**

## Connections

- Operator → Cartography CLI: runs sync (evidence: `README.md`)
- Cartography CLI → Sync Orchestrator: starts sync
- Sync Orchestrator → Provider Modules: selects modules
- Provider Modules → Provider APIs: fetches assets
- Provider Modules → Transform and Load: transforms assets (evidence: `cartography/intel/azure/storage.py`)
- Transform and Load → Graph Jobs: runs graph jobs (evidence: `cartography/intel/gcp/storage.py`)
- Transform and Load → Graph Schemas: loads schemas (evidence: `cartography/intel/azure/storage.py`)
- Transform and Load → Neo4j Transactions: writes records (evidence: `cartography/intel/gcp/storage.py`)
- Graph Jobs → Neo4j: executes queries
- Neo4j Transactions → Neo4j: writes graph
- Graph Schemas → Relationship Schemas: defines links (evidence: `cartography/models/kubernetes/storage.py`)
- Graph Schemas → Ontology Mapping: adds labels (evidence: `cartography/models/supabase/storagebucket.py`)
- Operator → Rules CLI: runs rules (evidence: `README.md`)
- Rules CLI → Security Rules: selects rules
- Security Rules → Rule Specification: uses definitions (evidence: `cartography/rules/data/rules/object_storage_public.py`)
- Rules CLI → Neo4j: queries graph (evidence: `README.md`)
- Operator → Graph Analysis: invokes analysis
- Operator → Drift CLI: runs drift checks
- Drift CLI → State Collection: collects states
- Drift CLI → Drift Storage: stores states
