# 10xgenomics/cellranger architecture

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

- Interactive diagram: https://gitdiagram.com/10xgenomics/cellranger
- Repository: https://github.com/10xgenomics/cellranger

## Overview

##### Main Components and Their Roles
- Input & Preprocessing: Represent components responsible for ingesting raw data, demultiplexing samples, and processing barcodes. This is evidenced by directories like “bin/rna”, “bin/sc_rna”, and “mro/rna”, which house scripts for different stages (e.g., cellranger demultiplexing, basic cell counting, barcode filtering).
- Analysis Pipelines: Identify distinct pipelines or modules for various analytical steps:
– Gene Counting & Expression Analysis (located in lib/python/cellranger/rna and corresponding mro pipelines)
– V(D)J Transcript Assembly (modules under lib/python/cellranger/vdj and mro/rna/stages/vdj)
– Feature Barcode Analysis
– CRISPR or Antibody specific tasks (see “lib/python/cellranger/feature”, “mro/rna/_crispr_analyzer.mro”, etc.)
- Core Libraries and Shared Utilities: Capture shared libraries in “lib” (with subfolders in Python, Go, and Rust) which implement common functionality like barcode correction, file I/O, telemetry (under lib/go/telemetry), and data conversions.
- Pipeline Orchestration: Highlight the “mro” directories that define the high-level stages in the pipeline. These “.mro” files contain the workflow definitions and stage orchestration logic used in analysis.
- External Dependencies & Third-Party Tools: Represent integration with external dependencies (contained in “third-party”) and build/deployment systems (.github workflows, configuration files like conda specs, etc.).

##### Relationships and Interactions
- Orchestration: Show how the “mro” stage files coordinate the execution between these components, initiating preflight checks, followed by sequential and parallel processing stages, and eventually generating summary reports.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize that the system is split into discrete pipelines—for example, separate modules for RNA counting and VDJ analysis—that likely follow a plug-and-play or microservice-like style within a single executable suite.
- Pipeline Staging: Indicate that stages are clearly demarcated (from preprocessing through analysis to postprocessing) using the “mro” definitions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input & Preprocessing"
        I1["RNA Preprocessing"] 
        I2["Single-Cell Preprocessing"]
        I3["Fastq Generation"]
    end

    subgraph "Pipeline Orchestration"
        P1["RNA Workflow Orchestrator"]
        P2["Tenkit Workflow Orchestrator"]
    end

    subgraph "Analysis Pipelines"
        subgraph "Gene Counting & Expression Analysis"
            A1["RNA Analysis Library"]
            A2["RNA Aggregator Stage"]
        end
        subgraph "V(D)J Transcript Assembly"
            V1["VDJ Analysis Library"]
            V2["VDJ Preflight Stage"]
        end
        subgraph "Feature Barcode Analysis"
            FBA1["Feature Analysis Library"]
            FBA2["CRISPR Analyzer Stage"]
        end
    end

    subgraph "Core Libraries & Shared Utilities"
        C1["Python Core Utilities"]
        C2["Go Telemetry Library"]
        C3["Rust Barcode Module"]
    end

    subgraph "Outputs & Reporting"
        O1["Reporting & Visualization"]
        O2["Telemetry Dashboard"]
    end

    subgraph "External Dependencies & Configurations"
        E1["Third-Party Tools"]
        E2["GitHub Configurations"]
        E3["Telemetry Config"]
    end

    %% Data flow arrows
    I1 --> P1
    I2 --> P1
    I3 --> P2

    P1 --> A1
    P1 --> A2
    P1 --> V1
    P1 --> V2
    P1 --> FBA1
    P1 --> FBA2

    %% Core libraries support connections
    C1 --- A1
    C1 --- A2
    C1 --- V1
    C1 --- V2
    C3 --- FBA1
    C3 --- FBA2
    C2 --- V1
    C2 --- V2

    %% Analysis pipelines produce outputs
    A1 --> O1
    A2 --> O1
    V1 --> O1
    V2 --> O1
    FBA1 --> O1
    FBA2 --> O1

    %% External dependencies feed into orchestration and outputs
    E1 --> P1
    E2 --> P1
    E1 --> O1
    E2 --> O1
    E3 --> O2

    %% Class definitions for styling
    classDef input fill:#ffebcd,stroke:#000,stroke-width:2px;
    classDef orchestration fill:#fafad2,stroke:#000,stroke-width:2px;
    classDef analysis fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef vdj fill:#87cefa,stroke:#000,stroke-width:2px;
    classDef feature fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef core fill:#e6e6fa,stroke:#000,stroke-width:2px;
    classDef output fill:#c1ffc1,stroke:#000,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:2px;

    %% Assign classes
    class I1,I2,I3 input;
    class P1,P2 orchestration;
    class A1,A2 analysis;
    class V1,V2 vdj;
    class FBA1,FBA2 feature;
    class C1,C2,C3 core;
    class O1,O2 output;
    class E1,E2,E3 external;

    %% Click Events for Component Mapping
    click I1 "https://github.com/10xgenomics/cellranger/tree/main/bin/rna"
    click I2 "https://github.com/10xgenomics/cellranger/tree/main/bin/sc_rna"
    click I3 "https://github.com/10xgenomics/cellranger/blob/main/mro/tenkit/make_fastqs.mro"
    click A1 "https://github.com/10xgenomics/cellranger/tree/main/lib/python/cellranger/rna"
    click A2 "https://github.com/10xgenomics/cellranger/blob/main/mro/rna/sc_rna_aggregator.mro"
    click V1 "https://github.com/10xgenomics/cellranger/tree/main/lib/python/cellranger/vdj"
    click V2 "https://github.com/10xgenomics/cellranger/tree/main/mro/rna/stages/vdj/vdj_preflight"
    click FBA1 "https://github.com/10xgenomics/cellranger/tree/main/lib/python/cellranger/feature"
    click FBA2 "https://github.com/10xgenomics/cellranger/blob/main/mro/rna/_crispr_analyzer.mro"
    click C1 "https://github.com/10xgenomics/cellranger/tree/main/lib/python"
    click C2 "https://github.com/10xgenomics/cellranger/tree/main/lib/go/telemetry"
    click C3 "https://github.com/10xgenomics/cellranger/tree/main/lib/rust/barcode"
    click P1 "https://github.com/10xgenomics/cellranger/tree/main/mro/rna"
    click P2 "https://github.com/10xgenomics/cellranger/tree/main/mro/tenkit"
    click E1 "https://github.com/10xgenomics/cellranger/tree/main/third-party"
    click E2 "https://github.com/10xgenomics/cellranger/blob/main/.github"
    click E3 "https://github.com/10xgenomics/cellranger/blob/main/etc/cellranger_telemetry.yaml"
```
