# rapidsai/cucim architecture

> Architecture diagram of the GitHub repository rapidsai/cucim, 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/rapidsai/cucim
- Repository: https://github.com/rapidsai/cucim

## Overview

##### Main Components
- Core Library (C++):
– Core framework and API: Found in cpp/src/core and related folders (framework initialization, plugin management, versioning).
– Modules for caching (cpp/src/cache), IO (cpp/src/io), file system handling, thread pooling (concurrent modules), and memory management.
– Utility modules (logger, configuration, macros, etc.).
- GPU Acceleration:
– Integration with CUDA (see references to CUDA kernels in core operations, cuda_kernel_source files, and dependencies like NVJPEG, rmm, etc.).
- Plugin Architecture:
– Separate plugins under cpp/plugins (e.g., cucim.kit.cumed and cucim.kit.cuslide) that extend the runtime with format-specific decoding (TIFF, SVS, JPEG2000, etc.).
- Python Bindings:
– Python interface module located in the python directory using pybind11 (with modules under python/pybind11 and python/cucim) to expose the same API as the C++ core.
- Build and Packaging Infrastructure:
– Build system via CMake (CMakeLists.txt files in various directories).
– CI/CD pipelines under the .github and ci directories.
– Packaging scripts for conda (conda/) and PyPI (python/cucim setup).
- Additional Elements:
– Benchmarks (for performance tests in benchmarks/ directory).
– Documentation, examples, notebooks (showing demo usage and integration).
– Third-party libraries and licenses (3rdparty directory).

##### Relationships and Interactions
- Within the C++ core, delineate submodules such as IO, caching, plugin management, and GPU-accelerated routines (kernel execution).
- Plugin modules with the core library, showing that they register with (or are discovered by) the plugin manager for format-specific operations.
- How the system integrates external dependencies (CUDA libraries, boost, etc.) which are managed via 3rdparty and CMake scripts.
- Data flow: Source image files (from disk or via GDS as seen in dependencies and experiments) are processed by the IO module, then passed through the caching/loader layers and finally processed with GPU-optimized operations.

##### Architectural Patterns and Design Principles
- Modular design: Core functionality is split into well-defined modules (IO, caching, memory, plugins) which simplifies maintenance and extension.
- Plugin Pattern: The use of separate components that can be dynamically loaded or compiled in to support additional image formats.
- Separation of Concerns: The distinct separation between the performance-critical C++/CUDA backend and the user-friendly Python front-end.
- Build and Distribution Abstraction: Clear use of CMake, CI workflows, and packaging across multiple platforms (conda, PyPI).

##### Relevant Technologies, Frameworks, and Libraries
- C++ with modern standards (utilizing C++20 features in some modules).
- CUDA for GPU acceleration.
- Pybind11 for Python bindings.
- External libraries such as Boost, CLI11, fmt, and others as listed in the 3rdparty folder.
- Various CMake scripts and modules that drive the build process.
- CI/CD tools integrated with GitHub Actions.

## Diagram (Mermaid)

```mermaid
graph TD
    %% C++ Core Library (Engine)
    subgraph "C++ Core Library (Engine)"
        A["Core Framework & API"]:::core
        B["Caching Modules"]:::core
        C["IO Modules"]:::core
        D["Memory Management"]:::core
        E["Plugin Management"]:::core
    end

    %% GPU Acceleration
    subgraph "GPU Acceleration (CUDA Kernels)"
        F["CUDA Utilities"]:::gpu
        G["CUDA Kernel - Color"]:::gpu
        H["CUDA Kernel - Intensity"]:::gpu
    end

    %% Plugin Architecture
    subgraph "Plugin Architecture"
        I["Plugin: cucim.kit.cumed"]:::plugin
        J["Plugin: cucim.kit.cuslide"]:::plugin
    end

    %% Python Bindings
    subgraph "Python Bindings (pybind11 Interface)"
        K["Python Interface Module"]:::python
        L["Pybind11 Binding Code"]:::python
    end

    %% Build and Packaging Infrastructure
    subgraph "Build and Packaging Infrastructure"
        M["Build System"]:::build
        N["CI/CD Pipelines"]:::build
        O["Packaging Scripts"]:::build
    end

    %% Benchmarks, Tests, and Documentation
    subgraph "Benchmarks, Tests, Documentation"
        P["Benchmarks"]:::peripheral
        Q["Tests"]:::peripheral
        R["Documentation"]:::peripheral
    end

    %% Relationships within C++ Core
    B -->|"feeds"| A
    C -->|"supplies data to"| A
    D -->|"manages memory for"| A
    E -->|"registers plugins with"| A

    %% Plugin Architecture registration
    I -->|"registers"| E
    J -->|"registers"| E

    %% GPU Acceleration integration
    A -->|"offloads GPU tasks to"| F
    F -->|"executes"| G
    F -->|"executes"| H

    %% Python Bindings using C++ Core
    K -->|"interfaces with"| A
    L -->|"binds to"| A

    %% Build and Packaging interactions (dashed connections)
    M ---|"builds"| A
    M ---|"builds"| K
    N ---|"runs pipelines for"| A
    N ---|"runs pipelines for"| K
    O ---|"packages"| A
    O ---|"packages"| K

    %% Benchmarks, Tests, Documentation interactions (dotted connections)
    P ---|"benchmarks"| A
    Q ---|"tests"| A
    R ---|"documents"| A

    %% Click Events for C++ Core Library
    click A "https://github.com/rapidsai/cucim/tree/branch-25.04/cpp/src/core"
    click B "https://github.com/rapidsai/cucim/tree/branch-25.04/cpp/src/cache"
    click C "https://github.com/rapidsai/cucim/tree/branch-25.04/cpp/src/io"
    click D "https://github.com/rapidsai/cucim/tree/branch-25.04/cpp/src/memory"
    click E "https://github.com/rapidsai/cucim/blob/branch-25.04/cpp/src/core/plugin_manager.cpp"

    %% Click Events for GPU Acceleration
    click F "https://github.com/rapidsai/cucim/blob/branch-25.04/cpp/include/cucim/util/cuda.h"
    click G "https://github.com/rapidsai/cucim/blob/branch-25.04/python/cucim/src/cucim/core/operations/color/kernel/cuda_kernel_source.py"
    click H "https://github.com/rapidsai/cucim/blob/branch-25.04/python/cucim/src/cucim/core/operations/intensity/kernel/cuda_kernel_source.py"

    %% Click Events for Plugin Architecture
    click I "https://github.com/rapidsai/cucim/blob/branch-25.04/cpp/plugins/cucim.kit.cumed"
    click J "https://github.com/rapidsai/cucim/blob/branch-25.04/cpp/plugins/cucim.kit.cuslide"

    %% Click Events for Python Bindings
    click K "https://github.com/rapidsai/cucim/tree/branch-25.04/python/cucim"
    click L "https://github.com/rapidsai/cucim/tree/branch-25.04/python/pybind11"

    %% Click Events for Build and Packaging
    click M "https://github.com/rapidsai/cucim/blob/branch-25.04/cpp/CMakeLists.txt"
    click N "https://github.com/rapidsai/cucim/tree/branch-25.04/.github/workflows"
    click O "https://github.com/rapidsai/cucim/tree/branch-25.04/conda/recipes"

    %% Click Events for Benchmarks, Tests, and Documentation
    click P "https://github.com/rapidsai/cucim/tree/branch-25.04/benchmarks/"
    click Q "https://github.com/rapidsai/cucim/tree/branch-25.04/cpp/tests"
    click R "https://github.com/rapidsai/cucim/tree/branch-25.04/docs/"

    %% Classes styling
    classDef core fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef gpu fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef plugin fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef python fill:#ffccee,stroke:#333,stroke-width:2px;
    classDef build fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef peripheral fill:#e0e0e0,stroke:#333,stroke-width:2px;
```
