# davidesantangelo/vsort architecture

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

- Interactive diagram: https://gitdiagram.com/davidesantangelo/vsort
- Repository: https://github.com/davidesantangelo/vsort

## Overview

##### Key Components
- API / Interface Layer: Start with the public APIs (vsort.h, vsort_logger.h) that external applications call into. This is the point where user data (arrays to be sorted) enters the system.
- Core Sorting Engine: Create a node for the core sorting functionality implemented in vsort.c and associated source files. Inside this module, note the hybrid approach which switches between:
– Insertion Sort (for very small arrays)
– Quicksort (with median-of-three pivot for general use)
– Parallelized sorting using the Parallel Merge technique
– Radix sort for large integer arrays
– NEON SIMD detection (for vectorization)
– Apple-specific P/E core detection via sysctl calls
– Cache size and CPU model identification
- Parallel Workload Dispatcher: Represent the integration with Grand Central Dispatch (GCD), which distributes the sorting/merging tasks across multiple cores. This component manages work-stealing and QoS scheduling between performance (P) cores and efficiency (E) cores.
- Dynamic Threshold & Auto-Calibration Module: Include a module that automatically tunes parameters (like chunk sizes, algorithm thresholds) based on runtime hardware characteristics. This is essential to the adaptive algorithm selection.
- Memory & Cache Optimization Module: Indicate component responsibilities for:
– Optimal memory alignment (cache-line alignment)
– Cache-aware chunk sizing tailored for Apple Silicon L2 cache (e.g., 128KB per core)
- Logging & Error Handling: Create a node for vsort_logger which encapsulates logging, error recovery, and debugging functionality.
– CMakeLists.txt, build_script.sh, and Makefile based flows
– Test suites from the tests directory and example programs (found in examples/) demonstrating use cases and benchmarks

##### Relationships and Data Flow
- The Memory & Cache Optimization component should have bidirectional interactions with the Core Sorting Engine to optimize data access during sorting operations.
- Finally, ensure there's a logging/error handling flow that monitors operations across these modules.

##### Architectural Patterns and Design Principles
- Hybrid design pattern – combining several sorting algorithms under an adaptive umbrella.
- Modular separation where one module handles hardware detection/auto-calibration and another manages sorting algorithm selection.
- That parallel task dispatching (through GCD) is an orthogonal but integral part of the overall design.
- That the system was designed for high scalability, performance, and hardware-specific optimizations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/API Interaction Cluster
    subgraph "User/API Interaction"
        API_VSORT["API: vsort.h"]:::api
        API_LOGGER["Logger API: vsort_logger.h"]:::api
    end

    %% Core Sorting Modules Cluster
    subgraph "Core Sorting Modules"
        CORE["Core Sorting Engine (vsort.c)"]:::engine
        INS["Insertion Sort"]:::algorithm
        QKS["Quicksort (Median-of-Three)"]:::algorithm
        RAD["Radix Sort"]:::algorithm
        PM["Parallel Merge"]:::algorithm
        DYNAMIC["Dynamic Threshold & Auto-Calibration"]:::engine
    end

    %% Hardware & Optimization Cluster
    subgraph "Hardware & Optimization"
        HW["Hardware Detection Module"]:::hardware
        MEM["Memory & Cache Optimization Module"]:::cache
    end

    %% Parallelism Cluster
    subgraph "Parallelism & Task Dispatch"
        PARALLEL["Parallel Workload Dispatcher (GCD)"]:::parallel
    end

    %% Logging & Error Handling Cluster
    subgraph "Logging & Error Handling"
        LOGGER_IMPL["Logger Implementation (vsort_logger.c)"]:::logger
    end

    %% Build & Testing Infrastructure Cluster
    subgraph "Build & Testing Infrastructure"
        CMAKE["Build System: CMakeLists.txt"]:::build
        BUILD_SCRIPT["Build Script: build_script.sh"]:::build
        TESTS["Tests Directory: tests/"]:::build
        EXAMPLES["Examples Directory: examples/"]:::build
    end

    %% Data Flow Connections
    API_VSORT -->|"calls"| CORE
    API_LOGGER -->|"initializes"| LOGGER_IMPL

    CORE -->|"AlgorithmSelection"| INS
    CORE -->|"AlgorithmSelection"| QKS
    CORE -->|"AlgorithmSelection"| RAD
    CORE -->|"AlgorithmSelection"| PM

    HW -->|"feeds hardwareInfo"| CORE
    HW -->|"influences"| DYNAMIC

    PARALLEL -->|"distributes tasks"| CORE
    CORE -->|"collects results"| PARALLEL

    MEM <-->|"optimizes memory"| CORE

    CORE -->|"logs events"| LOGGER_IMPL

    %% Styles for clarity and colors
    classDef api fill:#f6d186,stroke:#b8860b,stroke-width:2px;
    classDef engine fill:#f4a261,stroke:#e76f51,stroke-width:2px;
    classDef algorithm fill:#e9c46a,stroke:#f4a261,stroke-width:2px;
    classDef hardware fill:#2a9d8f,stroke:#264653,stroke-width:2px;
    classDef parallel fill:#e76f51,stroke:#d62828,stroke-width:2px;
    classDef cache fill:#a8dadc,stroke:#457b9d,stroke-width:2px;
    classDef logger fill:#8ecae6,stroke:#219ebc,stroke-width:2px;
    classDef build fill:#b7b7a4,stroke:#6b705c,stroke-width:2px;
    
    %% Click Events
    click API_VSORT "https://github.com/davidesantangelo/vsort/blob/master/vsort.h"
    click API_LOGGER "https://github.com/davidesantangelo/vsort/blob/master/vsort_logger.h"
    click CORE "https://github.com/davidesantangelo/vsort/blob/master/vsort.c"
    click LOGGER_IMPL "https://github.com/davidesantangelo/vsort/blob/master/vsort_logger.c"
    click CMAKE "https://github.com/davidesantangelo/vsort/blob/master/CMakeLists.txt"
    click BUILD_SCRIPT "https://github.com/davidesantangelo/vsort/blob/master/build_script.sh"
    click TESTS "https://github.com/davidesantangelo/vsort/tree/master/tests/"
    click EXAMPLES "https://github.com/davidesantangelo/vsort/tree/master/examples/"
```
