# akashkinkarpandey/multi-threaded-sorting architecture

> Architecture diagram of the GitHub repository akashkinkarpandey/multi-threaded-sorting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akashkinkarpandey/multi-threaded-sorting
- Repository: https://github.com/akashkinkarpandey/multi-threaded-sorting

## Overview

This repository is a small C++ console application centered on one algorithmic subsystem: merge sort. Its architecture is intentionally simple, with `src/main.cpp` acting as the entry point and two interchangeable sorting implementations under `src/sorting/`.

1. **Top-level shape**
   The project is organized as a single executable, not a library or service. There is no backend/frontend split, database, or network boundary. The main architectural decision is the comparison between a classic single-threaded merge sort and a parallelized version.

2. **Entry point and orchestration**
   `src/main.cpp` is the application driver. Based on the README, its role is likely to create or load input data, invoke both sorting implementations, and report results/performance. It is the only place where the two algorithms are coordinated, so it forms the boundary between “benchmark/demo logic” and “sorting logic.”

3. **Sorting subsystem**
   `src/sorting/` contains the reusable algorithm layer. It is split into:
   - `simpleMergeSort.*` for the sequential implementation
   - `parallelMergeSort.*` for the multi-threaded implementation  
   This separation makes the architecture easy to diagram as two sibling components under one sorting domain.

4. **Single-threaded path**
   The `simpleMergeSort` module represents the baseline algorithm. Its responsibility is pure sorting logic with no concurrency concerns. It is useful both as a correctness reference and as the performance comparison target.

5. **Parallel path**
   The `parallelMergeSort` module adds concurrency using `std::thread`. Architecturally, this is the main differentiator: it decomposes the input into subproblems, sorts parts in parallel, then merges results. The implementation likely manages thread creation and synchronization internally, but those details are encapsulated behind the module boundary.

6. **Data flow**
   The primary data flow is straightforward: `main.cpp` supplies an array/vector of values to one of the sorting modules, the module recursively partitions and sorts the data, and the sorted output is returned back to `main.cpp` for printing or benchmarking. There is no persistent storage; data exists only in memory during execution.

7. **Concurrency boundary**
   The parallel implementation is the only part of the repo that crosses a concurrency boundary. `std::thread` and `-pthread` are build/runtime requirements because the application depends on native OS thread support. This is important for an architecture diagram because the parallel sorter should be shown as a component that fans out work into worker threads and then joins before returning.

8. **Build and runtime model**
   The project is compiled directly with `g++` into a single executable. The build includes `src/main.cpp`, both sorting `.cpp` files, and links with pthread support. There is no build system file in the tree, so compilation is manual and linear rather than managed by CMake, Make, or a package manager.

9. **Headers and implementation pairing**
   The repository uses the common C++ split between `.hpp` interface declarations and `.cpp` implementations. This suggests the public surface of each sorter is defined in headers, while the algorithm details live in the corresponding source files. That creates a clean module boundary for diagramming, even though the repository is small.

10. **Comparison-oriented design**
   The README emphasizes performance benchmarking, so the application is not just “a sorter” but a comparison harness for algorithmic tradeoffs. The architecture should reflect that `main.cpp` is likely responsible for timing, invoking both implementations on equivalent inputs, and presenting speedup results.

11. **External dependencies**
   There are no external services, libraries, or frameworks involved beyond the C++ standard library and OS threading support. The only material technology choices are C++11-or-later, `std::thread`, and pthread linkage on the build target.

12. **What is not present**
   This repo does not appear to include a server, UI, test suite, or benchmark automation scripts. The diagram should therefore stay focused on a single-process executable with two algorithm modules and an in-memory data path.

In short: the architecture is a single-command-line C++ program where `main.cpp` drives a benchmarking/comparison workflow, and the core domain logic lives in two sibling sorting modules—one sequential, one parallel—with threading encapsulated entirely inside the parallel sorter.

Main entry points: [`src/main.cpp`](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/main.cpp) (Main app), [`src/sorting/parallelMergeSort.cpp`](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/parallelMergeSort.cpp) (Parallel sort), [`src/sorting/simpleMergeSort.cpp`](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/simpleMergeSort.cpp) (Simple sort), [`src/sorting/simpleMergeSort.hpp`](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/simpleMergeSort.hpp) (Simple API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sorting["Sorting subsystem"]
  node_simple_sort{{"Simple sort<br/>sequential merge sort"}}
  node_simple_hdr["Simple API<br/>sort interface"]
  node_parallel_sort{{"Parallel sort<br/>threaded merge sort"}}
  node_parallel_hdr["Parallel API<br/>sort interface"]
end

node_main["Main app<br/>CLI driver<br/>[main.cpp]"]
node_threads(("Worker threads<br/>std::thread runtime"))
node_report["Results<br/>timing/output"]

node_main -->|"invokes"| node_simple_hdr
node_main -->|"invokes"| node_parallel_hdr
node_simple_hdr -->|"declares"| node_simple_sort
node_parallel_hdr -->|"declares"| node_parallel_sort
node_parallel_sort -->|"spawns"| node_threads
node_threads -->|"joins"| node_parallel_sort
node_main -->|"prints"| node_report
node_simple_sort -.->|"feeds"| node_report
node_parallel_sort -.->|"feeds"| node_report
node_main -.->|"benchmarks"| node_simple_sort
node_main -.->|"benchmarks"| node_parallel_sort

click node_main "https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/main.cpp"
click node_simple_sort "https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/simpleMergeSort.cpp"
click node_simple_hdr "https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/simpleMergeSort.hpp"
click node_parallel_sort "https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/parallelMergeSort.cpp"
click node_parallel_hdr "https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/parallelMergeSort.hpp"

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_simple_sort,node_simple_hdr,node_parallel_sort,node_parallel_hdr toneBlue
class node_main,node_threads,node_report toneNeutral
```

## Components

### Sorting subsystem

Reusable merge sort implementations and their headers.

- [Simple sort](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/simpleMergeSort.cpp): sequential merge sort · Baseline single-threaded merge sort implementation used for correctness and performance comparison. · `src/sorting/simpleMergeSort.cpp`
- [Simple API](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/simpleMergeSort.hpp): sort interface · Header declaring the sequential merge sort surface. · `src/sorting/simpleMergeSort.hpp`
- [Parallel sort](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/parallelMergeSort.cpp): threaded merge sort · Multi-threaded merge sort implementation that splits work across threads and merges results. · `src/sorting/parallelMergeSort.cpp`
- [Parallel API](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/sorting/parallelMergeSort.hpp): sort interface · Header declaring the parallel merge sort surface. · `src/sorting/parallelMergeSort.hpp`

### Other components

- [Main app](https://github.com/akashkinkarpandey/multi-threaded-sorting/blob/main/src/main.cpp): CLI driver · Entry point that prepares input, runs the sorting comparison, and reports results. · `src/main.cpp`
- **Worker threads**: std::thread runtime · Native concurrency used internally by the parallel sorter to execute subproblems concurrently.
- **Results**: timing/output · Comparison output produced by the application after sorting and benchmarking.

## Connections

- Main app → Simple API: invokes · Main coordinates the baseline sort through its public interface.
- Main app → Parallel API: invokes · Main coordinates the parallel sort through its public interface.
- Simple API → Simple sort: declares · The header exposes the sequential implementation.
- Parallel API → Parallel sort: declares · The header exposes the parallel implementation.
- Parallel sort → Worker threads: spawns · The parallel sorter creates worker threads to process partitions concurrently.
- Worker threads → Parallel sort: joins · Worker threads complete before the parallel sorter returns merged output.
- Main app → Results: prints · The driver emits sorted output and/or benchmark results.
- Simple sort → Results: feeds · Baseline results are compared against the report output.
- Parallel sort → Results: feeds · Parallel results are compared against the report output.
- Main app → Simple sort: benchmarks · The application likely runs the baseline implementation as part of the comparison workflow.
- Main app → Parallel sort: benchmarks · The application likely runs the parallel implementation as part of the comparison workflow.
