# 10xgenomics/spaceranger architecture

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

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

## Overview

##### Major Components
- Input and Preprocessing: Represent modules that take raw sequencing files (fastq), imaging data (brightfield/fluorescence images), and reference files. This includes components within “bin” and “mro” (workflow definitions) that launch preprocessing steps such as generating fastq files and preparing references.
- Pipeline Orchestration: Highlight the “mro” directory which contains a large number of workflow definition files (the .mro scripts) that represent different pipeline stages (aggregator, analyzer, spatial, targeted, tenkit). This acts as an orchestration layer that sequences and controls execution.
- Core Processing Libraries: Illustrate critical computation modules found in “lib”. Show the separation by language and purpose:
▪ Python components: Located under “lib/python”, especially the “cellranger” modules, which contain algorithms for analysis (PCA, clustering, antibody and spatial analysis, etc.).
▪ Go components: Used for specific functionalities such as “sitecheck” and demultiplexing routines, indicating performance or concurrency requirements.
▪ Rust components: Represented in “lib/rust”; these are performance-centric modules handling barcode processing, demultiplexing, alignment, and statistical calculations. They include submodules (cr_aggr, cr_lib, spatial, etc.) that power core mathematical or I/O routines.
- Reporting and Web Summary Generation: Include the “websummary” and related directories. These take processed data and convert it into human-readable summaries, dashboards, metrics, and image processing outputs.
- Third-party Dependencies: Don’t forget external integrations and build dependencies (STAR, BWA, Conda environments, etc.) which are defined under “third-party”. This layer is critical to show where external tools are used or patched.
- Configuration and Build Tools: Mention configurations and build scripts (like Cargo.toml files, .cargo configuration, and build scripts in “third-party”) that orchestrate the various languages and deployment artifacts.

##### Relationships and Data Flow
- That once input data is preprocessed, it goes to analysis stages (cell-calling, demultiplexing, clustering) which are implemented across the Python, Go, and Rust layers.
- Link processing modules with each other: for instance, the output of the “tenkit” submodules (which handle fastq generation and preflight checks) flows into analysis steps in “cellranger” and then further into the reporting modules.
- That the workflow orchestration (mro files) acts as the conductor that triggers these independent modules in sequence.

##### Architectural Patterns and Design Principles
- Pipeline/Modular Architecture: Emphasize that the design is modular, with each component dedicated to a particular step in the analysis. This modularity is clear from the strict separation of stages (aggregator, analyzer, spatial, targeted, etc.)

- Use clear labels for each major block: “Input & Preprocessing”, “Workflow Orchestration (MRO)”, “Core Analysis – Python (cellranger)”, “Core Analysis – Rust (cr_lib, spatial, etc.)”, “Core Analysis – Go (sitecheck)”, “Reporting & Web Summary”, “Third-party Tools”, and “Configuration/Build Infrastructure”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Preprocessing
    subgraph "Input & Preprocessing"
        A["Raw Data Processing (bin/tenkit)"]:::preprocessing
        B["Preprocessing Workflow (mro/tenkit)"]:::preprocessing
    end

    %% Pipeline Orchestration
    C["Pipeline Orchestration (MRO Workflows)"]:::orchestration

    %% Core Processing
    subgraph "Core Processing"
        D["Python (cellranger)"]:::python
        subgraph "Go Components"
            E1["Go: sitecheck"]:::go
            E2["Go: tenkit utilities"]:::go
        end
        F["Rust (Barcode, Demux, Alignment)"]:::rust
    end

    %% Reporting & Web Summary
    G["Reporting & Web Summary"]:::reporting

    %% External Dependencies
    subgraph "External Dependencies"
        H["Third-party Dependencies"]:::thirdparty
        I["Configuration & Build Tools"]:::configuration
    end

    %% Data Flow Connections
    A --> C
    B --> C
    C --> D
    C --> E1
    C --> E2
    C --> F
    D --> G
    E1 --> G
    E2 --> G
    F --> G

    %% Dependency Relationships (dashed lines)
    H -.-> D
    H -.-> E1
    H -.-> E2
    H -.-> F
    I -.-> D
    I -.-> F

    %% Click Events
    click A "https://github.com/10xgenomics/spaceranger/tree/main/bin/tenkit"
    click B "https://github.com/10xgenomics/spaceranger/blob/main/mro/tenkit/make_fastqs.mro"
    click C "https://github.com/10xgenomics/spaceranger/tree/main/mro/rna"
    click D "https://github.com/10xgenomics/spaceranger/tree/main/lib/python/cellranger"
    click E1 "https://github.com/10xgenomics/spaceranger/tree/main/lib/go/cmd/sitecheck"
    click E2 "https://github.com/10xgenomics/spaceranger/tree/main/lib/go/tenkit"
    click F "https://github.com/10xgenomics/spaceranger/tree/main/lib/rust"
    click G "https://github.com/10xgenomics/spaceranger/tree/main/lib/python/cellranger/websummary"
    click H "https://github.com/10xgenomics/spaceranger/tree/main/third-party"
    click I "https://github.com/10xgenomics/spaceranger/blob/main/lib/rust/Cargo.toml"

    %% Styles
    classDef preprocessing fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef orchestration fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef python fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef go fill:#fde2e4,stroke:#d63384,stroke-width:2px;
    classDef rust fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef reporting fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef thirdparty fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef configuration fill:#e2eaff,stroke:#084298,stroke-width:2px;
```
