# starbuck7410/avx-sort architecture

> Architecture diagram of the GitHub repository starbuck7410/avx-sort, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/starbuck7410/avx-sort
- Repository: https://github.com/starbuck7410/avx-sort

## Overview

1. **Repository purpose**
   - This is a small native C project focused on comparing a conventional sorting implementation against a SIMD/AVX-optimized version.
   - The codebase also includes build automation to validate that the project can be generated and built with CMake and Visual Studio tooling.

2. **Top-level shape**
   - The repo is organized into three main areas:
     - `src/` for executable and algorithm implementations
     - `include/` for public headers
     - `.github/workflows/` for CI/build automation
   - `CMakeLists.txt` is the central build definition tying the C sources into one buildable target.

3. **Executable entry point**
   - `src/main.c` is the program entry point.
   - Its role is to drive the sort comparison/benchmark flow: set up input, invoke the sort implementation(s), and likely print timing or result information.
   - This file sits at the top of the runtime flow and depends on the sorting APIs exposed by the headers.

4. **Scalar sort subsystem**
   - `src/sort.c` paired with `include/sort.h` is the non-SIMD sorting path.
   - This is the baseline algorithm used for comparison, and it forms one side of the project’s performance experiment.
   - The header boundary suggests the sort implementation is meant to be called from outside the module rather than being embedded only in `main.c`.

5. **SIMD sort subsystem**
   - `src/simd_sort.c` paired with `include/simd_sort.h` contains the AVX/SIMD-based variant.
   - This is the experimental optimization path and the core technical focus of the repo.
   - The presence of a separate header indicates the SIMD code is isolated behind its own API boundary, which is useful for swapping implementations or comparing them directly.

6. **Data flow through the program**
   - `main.c` likely creates or loads a data set, then passes the same or comparable inputs into the scalar and SIMD sort routines.
   - The output is presumably the sorted result plus benchmark data or validation checks to confirm correctness and compare speed.
   - The important architectural flow is: input setup → sort API call → result verification / timing output.

7. **Compilation and portability boundary**
   - `CMakeLists.txt` is the build-system hub and is especially important here because the README explicitly calls out portable builds and Visual Studio generation.
   - This means the project is not just “compile these files”; the build layer is part of the repo’s architecture, abstracting compiler/platform differences.
   - It likely controls which source files are compiled into the executable and may gate AVX-related compiler flags.

8. **Windows/Visual Studio CI**
   - `.github/workflows/windows-build.yml` automates a Windows build path, specifically to generate or validate Visual Studio project files via CMake.
   - This is a tooling subsystem rather than runtime code, but it matters architecturally because it enforces that the build configuration works outside a local environment.
   - The CI boundary is focused on build generation/compatibility rather than deployment.

9. **Public API design**
   - The `include/` directory separates interface from implementation, which suggests the sorting functions are intended to be consumed through stable function declarations.
   - This is the key modular boundary in the project: `main.c` and any future callers should depend on headers, not source internals.
   - That separation makes the scalar and SIMD implementations independently maintainable.

10. **What is not present**
   - There is no evidence of a network service, database, GUI, or multi-process system.
   - Architecturally this is a single-process native benchmarking program with a supporting build pipeline.
   - The complexity is concentrated in algorithm choice and build portability, not distributed system concerns.

11. **Likely diagram emphasis**
   - A useful architecture diagram would show:
     - one executable
     - one entry point (`main.c`)
     - two interchangeable sorting modules (`sort.c` and `simd_sort.c`)
     - header-based API boundaries
     - CMake as the build orchestrator
     - GitHub Actions as the CI/build-validation layer

12. **Core takeaway**
   - The repository is essentially a performance experiment wrapped in a portable CMake-based build setup.
   - Its main architectural distinction is the split between baseline and AVX-optimized sorting, with the rest of the repo supporting compilation, comparison, and automated build verification.

Main entry points: [`CMakeLists.txt`](https://github.com/starbuck7410/avx-sort/blob/main/CMakeLists.txt) (CMakeLists), [`src/main.c`](https://github.com/starbuck7410/avx-sort/blob/main/src/main.c) (main.c), [`include/sort.h`](https://github.com/starbuck7410/avx-sort/blob/main/include/sort.h) (sort.h), [`include/simd_sort.h`](https://github.com/starbuck7410/avx-sort/blob/main/include/simd_sort.h) (simd_sort.h)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["main.c<br/>entrypoint<br/>[main.c]"]
  node_sort_api["sort.h<br/>scalar api<br/>[sort.h]"]
  node_simd_api["simd_sort.h<br/>simd api<br/>[simd_sort.h]"]
  node_sort_impl["sort.c<br/>scalar impl<br/>[sort.c]"]
  node_simd_impl["simd_sort.c<br/>avx impl<br/>[simd_sort.c]"]
  node_app(("sort benchmark<br/>native app"))
end

subgraph group_build["Build"]
  node_cmake["CMakeLists<br/>build config<br/>[CMakeLists.txt]"]
end

subgraph group_ci["CI"]
  node_windows_ci["windows-build<br/>ci workflow<br/>[windows-build.yml]"]
end

node_main -->|"uses"| node_sort_api
node_main -->|"uses"| node_simd_api
node_sort_api -->|"declares"| node_sort_impl
node_simd_api -->|"declares"| node_simd_impl
node_cmake -->|"builds"| node_main
node_cmake -->|"builds"| node_sort_impl
node_cmake -->|"builds"| node_simd_impl
node_cmake -->|"exposes"| node_sort_api
node_cmake -->|"exposes"| node_simd_api
node_cmake -->|"defines"| node_app
node_windows_ci -->|"validates"| node_cmake

click node_main "https://github.com/starbuck7410/avx-sort/blob/main/src/main.c"
click node_sort_api "https://github.com/starbuck7410/avx-sort/blob/main/include/sort.h"
click node_simd_api "https://github.com/starbuck7410/avx-sort/blob/main/include/simd_sort.h"
click node_sort_impl "https://github.com/starbuck7410/avx-sort/blob/main/src/sort.c"
click node_simd_impl "https://github.com/starbuck7410/avx-sort/blob/main/src/simd_sort.c"
click node_cmake "https://github.com/starbuck7410/avx-sort/blob/main/CMakeLists.txt"
click node_windows_ci "https://github.com/starbuck7410/avx-sort/blob/main/.github/workflows/windows-build.yml"

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_main,node_sort_api,node_simd_api,node_sort_impl,node_simd_impl,node_app toneBlue
class node_cmake toneAmber
class node_windows_ci toneMint
```

## Components

### Runtime

Single-process benchmark flow and sort implementations

- [main.c](https://github.com/starbuck7410/avx-sort/blob/main/src/main.c): entrypoint · Program entry point that drives input setup, sorting, and comparison output · `src/main.c`
- [sort.h](https://github.com/starbuck7410/avx-sort/blob/main/include/sort.h): scalar api · Public interface for the baseline sorting path · `include/sort.h`
- [simd_sort.h](https://github.com/starbuck7410/avx-sort/blob/main/include/simd_sort.h): simd api · Public interface for the AVX/SIMD sorting path · `include/simd_sort.h`
- [sort.c](https://github.com/starbuck7410/avx-sort/blob/main/src/sort.c): scalar impl · Conventional sorting implementation used as the baseline · `src/sort.c`
- [simd_sort.c](https://github.com/starbuck7410/avx-sort/blob/main/src/simd_sort.c): avx impl · SIMD/AVX-optimized sorting implementation · `src/simd_sort.c`
- **sort benchmark**: native app · Built executable that compares baseline and SIMD sorting

### Build

CMake-driven native build definition

- [CMakeLists](https://github.com/starbuck7410/avx-sort/blob/main/CMakeLists.txt): build config · Central build definition that assembles the executable and compiler settings · `CMakeLists.txt`

### CI

Windows build validation workflow

- [windows-build](https://github.com/starbuck7410/avx-sort/blob/main/.github/workflows/windows-build.yml): ci workflow · GitHub Actions workflow that validates Windows/CMake build generation · `.github/workflows/windows-build.yml`

## Connections

- main.c → sort.h: uses · Main program calls the baseline sort API
- main.c → simd_sort.h: uses · Main program calls the SIMD sort API
- sort.h → sort.c: declares · Header boundary for the scalar implementation
- simd_sort.h → simd_sort.c: declares · Header boundary for the AVX implementation
- CMakeLists → main.c: builds · CMake includes the entry point in the executable target
- CMakeLists → sort.c: builds · CMake compiles the baseline sorting source
- CMakeLists → simd_sort.c: builds · CMake compiles the SIMD sorting source
- CMakeLists → sort.h: exposes · Build includes public scalar headers
- CMakeLists → simd_sort.h: exposes · Build includes public SIMD headers
- CMakeLists → sort benchmark: defines · CMake defines the native benchmark executable
- windows-build → CMakeLists: validates · Workflow checks CMake generation and Windows build compatibility