# lyft/cartography architecture

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

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

## Overview

Cartography collects infrastructure and identity data from many platforms, models assets and relationships, and syncs them into Neo4j for querying and security analysis. The main workflow is selecting a data source, collecting its inventory, writing graph data, then querying the graph or running security rules. Its model and graph-job layers build and execute graph operations; analysis and ontology modules add derived insights. The README documents broad platform coverage and rules; source excerpts show graph ingestion mechanics, but not the full CLI dispatch or every integration.

Main entry points: [`cartography/graph/job.py`](https://github.com/lyft/cartography/blob/master/cartography/graph/job.py) (Graph Jobs), [`cartography/cli.py`](https://github.com/lyft/cartography/blob/master/cartography/cli.py) (CLI), [`cartography/graph/querybuilder.py`](https://github.com/lyft/cartography/blob/master/cartography/graph/querybuilder.py) (Query Builder), [`cartography/rules`](https://github.com/lyft/cartography/tree/master/cartography/rules) (Security Rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Collection and Sync"]
  node_cli["CLI<br/>[cli.py]"]
  node_platforms["Platform Collectors"]
  node_azure_storage["Azure Storage<br/>[storage.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_graph["Graph Engine"]
  node_graph_jobs["Graph Jobs<br/>[job.py]"]
  node_statements["Graph Statements<br/>[statement.py]"]
  node_query_builder["Query Builder<br/>[querybuilder.py]"]
  node_analysis_builder["Analysis Builder<br/>[analysisbuilder.py]"]
  node_cleanup_builder["Cleanup Builder<br/>[cleanupbuilder.py]"]
  node_tx["Neo4j Transactions<br/>[tx.py]"]
  node_core_schema["Core Schemas"]
  node_ontology_schema["Ontology Schema"]
  node_stats["Statistics<br/>[stats.py]"]
end

subgraph group_insights["Analysis and Ontology"]
  node_analysis["Cloud Analysis<br/>[analysis.py]"]
  node_ontology_analysis["Ontology Analysis<br/>[analysis.py]"]
end

subgraph group_security["Security Checks"]
  node_rules["Security Rules"]
  node_rule_model["Rule Model<br/>[model.py]"]
end

subgraph group_drift["Drift Detection"]
  node_drift_cli["Drift CLI<br/>[cli.py]"]
  node_drift_detection["Deviation Detection"]
  node_drift_storage["Drift Storage<br/>[storage.py]"]
end

node_operator(("Operator"))
node_neo4j[("Neo4j")]

node_operator -->|"runs"| node_cli
node_cli -.->|"selects modules"| node_platforms
node_cli -.->|"configures"| node_config
node_platforms -->|"syncs inventory"| node_neo4j
node_azure_storage -->|"runs jobs"| node_graph_jobs
node_graph_jobs -->|"executes"| node_statements
node_graph_jobs -->|"builds cleanup"| node_cleanup_builder
node_graph_jobs -.->|"executes queries"| node_tx
node_tx -->|"uses queries"| node_query_builder
node_query_builder -->|"maps schemas"| node_core_schema
node_query_builder -->|"maps ontology"| node_ontology_schema
node_analysis_builder -.->|"builds analysis jobs"| node_analysis
node_analysis -.->|"analyzes graph"| node_neo4j
node_ontology_analysis -.->|"analyzes graph"| node_neo4j
node_operator -->|"runs checks"| node_rules
node_rules -->|"uses definitions"| node_rule_model
node_rules -->|"queries graph"| node_neo4j
node_operator -.->|"runs"| node_drift_cli
node_drift_cli -.->|"dispatches"| node_drift_detection
node_drift_detection -.->|"uses storage"| node_drift_storage

click node_cli "https://github.com/lyft/cartography/blob/master/cartography/cli.py"
click node_platforms "https://github.com/lyft/cartography/tree/master/cartography/intel"
click node_azure_storage "https://github.com/lyft/cartography/blob/master/cartography/intel/azure/storage.py"
click node_config "https://github.com/lyft/cartography/blob/master/cartography/config.py"
click node_graph_jobs "https://github.com/lyft/cartography/blob/master/cartography/graph/job.py"
click node_statements "https://github.com/lyft/cartography/blob/master/cartography/graph/statement.py"
click node_query_builder "https://github.com/lyft/cartography/blob/master/cartography/graph/querybuilder.py"
click node_analysis_builder "https://github.com/lyft/cartography/blob/master/cartography/graph/analysisbuilder.py"
click node_cleanup_builder "https://github.com/lyft/cartography/blob/master/cartography/graph/cleanupbuilder.py"
click node_tx "https://github.com/lyft/cartography/blob/master/cartography/client/core/tx.py"
click node_core_schema "https://github.com/lyft/cartography/tree/master/cartography/models/core"
click node_ontology_schema "https://github.com/lyft/cartography/tree/master/cartography/models/ontology"
click node_analysis "https://github.com/lyft/cartography/blob/master/cartography/analysis/aws/analysis.py"
click node_ontology_analysis "https://github.com/lyft/cartography/blob/master/cartography/analysis/ontology/analysis.py"
click node_rules "https://github.com/lyft/cartography/tree/master/cartography/rules"
click node_rule_model "https://github.com/lyft/cartography/blob/master/cartography/rules/spec/model.py"
click node_drift_cli "https://github.com/lyft/cartography/blob/master/cartography/driftdetect/cli.py"
click node_drift_detection "https://github.com/lyft/cartography/blob/master/cartography/driftdetect/detect_deviations.py"
click node_drift_storage "https://github.com/lyft/cartography/blob/master/cartography/driftdetect/storage.py"
click node_stats "https://github.com/lyft/cartography/blob/master/cartography/stats.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_platforms,node_azure_storage,node_config toneBlue
class node_graph_jobs,node_statements,node_query_builder,node_analysis_builder,node_cleanup_builder,node_tx,node_core_schema,node_ontology_schema,node_stats,node_neo4j toneAmber
class node_analysis,node_ontology_analysis toneMint
class node_rules,node_rule_model toneRose
class node_drift_cli,node_drift_detection,node_drift_storage,node_operator toneIndigo
```

## Components

### Collection and Sync

- [CLI](https://github.com/lyft/cartography/blob/master/cartography/cli.py): `cartography/cli.py`
- [Platform Collectors](https://github.com/lyft/cartography/tree/master/cartography/intel): `cartography/intel`
- [Azure Storage](https://github.com/lyft/cartography/blob/master/cartography/intel/azure/storage.py): `cartography/intel/azure/storage.py`
- [Configuration](https://github.com/lyft/cartography/blob/master/cartography/config.py): `cartography/config.py`

### Graph Engine

- [Graph Jobs](https://github.com/lyft/cartography/blob/master/cartography/graph/job.py): `cartography/graph/job.py`
- [Graph Statements](https://github.com/lyft/cartography/blob/master/cartography/graph/statement.py): `cartography/graph/statement.py`
- [Query Builder](https://github.com/lyft/cartography/blob/master/cartography/graph/querybuilder.py): `cartography/graph/querybuilder.py`
- [Analysis Builder](https://github.com/lyft/cartography/blob/master/cartography/graph/analysisbuilder.py): `cartography/graph/analysisbuilder.py`
- [Cleanup Builder](https://github.com/lyft/cartography/blob/master/cartography/graph/cleanupbuilder.py): `cartography/graph/cleanupbuilder.py`
- [Neo4j Transactions](https://github.com/lyft/cartography/blob/master/cartography/client/core/tx.py): `cartography/client/core/tx.py`
- [Core Schemas](https://github.com/lyft/cartography/tree/master/cartography/models/core): `cartography/models/core`
- [Ontology Schema](https://github.com/lyft/cartography/tree/master/cartography/models/ontology): `cartography/models/ontology`
- [Statistics](https://github.com/lyft/cartography/blob/master/cartography/stats.py): `cartography/stats.py`

### Analysis and Ontology

- [Cloud Analysis](https://github.com/lyft/cartography/blob/master/cartography/analysis/aws/analysis.py): `cartography/analysis/aws/analysis.py`
- [Ontology Analysis](https://github.com/lyft/cartography/blob/master/cartography/analysis/ontology/analysis.py): `cartography/analysis/ontology/analysis.py`

### Security Checks

- [Security Rules](https://github.com/lyft/cartography/tree/master/cartography/rules): `cartography/rules`
- [Rule Model](https://github.com/lyft/cartography/blob/master/cartography/rules/spec/model.py): `cartography/rules/spec/model.py`

### Drift Detection

- [Drift CLI](https://github.com/lyft/cartography/blob/master/cartography/driftdetect/cli.py): `cartography/driftdetect/cli.py`
- [Deviation Detection](https://github.com/lyft/cartography/blob/master/cartography/driftdetect/detect_deviations.py): `cartography/driftdetect/detect_deviations.py`
- [Drift Storage](https://github.com/lyft/cartography/blob/master/cartography/driftdetect/storage.py): `cartography/driftdetect/storage.py`

### Other components

- **Operator**
- **Neo4j**

## Connections

- Operator → CLI: runs
- CLI → Platform Collectors: selects modules
- CLI → Configuration: configures
- Platform Collectors → Neo4j: syncs inventory
- Azure Storage → Graph Jobs: runs jobs (evidence: `cartography/intel/azure/storage.py`)
- Graph Jobs → Graph Statements: executes (evidence: `cartography/graph/job.py`)
- Graph Jobs → Cleanup Builder: builds cleanup (evidence: `cartography/graph/job.py`)
- Graph Jobs → Neo4j Transactions: executes queries
- Neo4j Transactions → Query Builder: uses queries (evidence: `cartography/client/core/tx.py`)
- Query Builder → Core Schemas: maps schemas (evidence: `cartography/graph/querybuilder.py`)
- Query Builder → Ontology Schema: maps ontology (evidence: `cartography/graph/querybuilder.py`)
- Analysis Builder → Cloud Analysis: builds analysis jobs
- Cloud Analysis → Neo4j: analyzes graph
- Ontology Analysis → Neo4j: analyzes graph
- Operator → Security Rules: runs checks
- Security Rules → Rule Model: uses definitions (evidence: `cartography/rules/data/rules/object_storage_public.py`)
- Security Rules → Neo4j: queries graph
- Operator → Drift CLI: runs
- Drift CLI → Deviation Detection: dispatches
- Deviation Detection → Drift Storage: uses storage
