# ulsgks/push_swap architecture

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

- Interactive diagram: https://gitdiagram.com/ulsgks/push_swap
- Repository: https://github.com/ulsgks/push_swap

## Overview

Push Swap sorts integer inputs using two stacks and emits a sequence of stack operations; the bonus checker reads such a sequence, applies it, and reports whether the result is sorted. The documented algorithm includes chunk sorting and several small-sort and post-sort optimizations. The graph preserves these stages, but several algorithm-to-optimizer relationships are dashed because their source excerpts were not provided. The stack operations and shared utility libraries are internal supporting layers.

Main entry points: [`src/push_swap/chunk_sort.c`](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/chunk_sort.c) (Chunk sorting), [`src/push_swap/main.c`](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/main.c) (Push Swap CLI), [`src/checker_bonus/checker_bonus.c`](https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_bonus.c) (Checker CLI), [`src/stack/data_mngt.c`](https://github.com/ulsgks/push_swap/blob/main/src/stack/data_mngt.c) (Stack lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Programs and validation"]
  node_sort_main["Push Swap CLI<br/>[main.c]"]
  node_checker_main["Checker CLI<br/>[checker_bonus.c]"]
  node_checker_io["Read operations<br/>[checker_bonus.c]"]
  node_checker_apply["Apply and check<br/>[checker_bonus.c]"]
  node_checker_helpers["Checker helpers"]
  node_checker_header["Checker interfaces<br/>[checker_bonus.h]"]
end

subgraph group_algorithm["Sorting algorithm"]
  node_sort_core["Sort orchestration<br/>[sort.c]"]
  node_chunk_sort["Chunk sorting<br/>[chunk_sort.c]"]
  node_chunk_split["Chunk splitting<br/>[chunk_split.c]"]
  node_chunk_utils["Chunk utilities<br/>[chunk_utils.c]"]
  node_move["Chunk movement<br/>[move.c]"]
  node_easy_sort["Easy-sort optimization<br/>[opti_easy_sort.c]"]
  node_sort_three["Three-item sorting<br/>[opti_sort_three.c]"]
  node_sort_asap["Early-sort optimization<br/>[opti_sort_asap.c]"]
  node_post_sort["Post-sort optimization<br/>[opti_post_sort.c]"]
  node_post_sort_utils["Optimization helpers"]
  node_to_top["Chunk positioning<br/>[opti_to_the_top.c]"]
  node_push_header["Sort interfaces<br/>[push_swap.h]"]
end

subgraph group_stacks["Stack runtime"]
  node_stack_data["Stack lifecycle<br/>[data_mngt.c]"]
  node_stack_init["Input validation and ranking<br/>[stack_init.c]"]
  node_stack_utils["Stack queries<br/>[stack_utils.c]"]
  node_stack_ops["Stack operations<br/>[op_push.c]"]
  node_stack_rotate["Rotation operations<br/>[op_rotate.c]"]
  node_stack_reverse["Reverse rotations"]
  node_stack_swap["Swap operations<br/>[op_swap.c]"]
  node_op_utils["Operation encoding<br/>[op_utils.c]"]
  node_stack_header["Stack interfaces<br/>[stack.h]"]
end

subgraph group_utilities["Utility libraries"]
  node_libft["C utility functions<br/>[libft.h]"]
  node_ft_printf["Formatted output<br/>[ft_printf.h]"]
end

node_user(("CLI user"))

node_user -->|"provides input"| node_sort_main
node_sort_main -->|"initializes data"| node_stack_data
node_sort_main -->|"sorts stacks"| node_sort_core
node_sort_main -->|"prints operations"| node_op_utils
node_sort_main -->|"frees data"| node_stack_data
node_stack_data -->|"fills stack"| node_stack_init
node_stack_init -->|"parses numbers"| node_libft
node_sort_core -.->|"dispatches sorting"| node_chunk_sort
node_chunk_sort -.->|"splits chunks"| node_chunk_split
node_chunk_sort -.->|"uses chunk queries"| node_chunk_utils
node_chunk_sort -.->|"moves elements"| node_move
node_chunk_sort -.->|"optimizes small chunks"| node_easy_sort
node_chunk_sort -.->|"sorts three items"| node_sort_three
node_chunk_sort -.->|"reduces chunk work"| node_sort_asap
node_chunk_sort -.->|"positions chunks"| node_to_top
node_sort_core -.->|"optimizes operations"| node_post_sort
node_post_sort -.->|"uses helpers"| node_post_sort_utils
node_user -->|"provides input"| node_checker_main
node_checker_main -->|"initializes data"| node_stack_data
node_checker_main -->|"reads operations"| node_checker_io
node_checker_main -->|"checks result"| node_checker_apply
node_checker_apply -->|"applies operations"| node_checker_helpers
node_checker_io -->|"decodes operations"| node_checker_helpers
node_checker_apply -.->|"dispatches operations"| node_stack_ops
node_stack_header -->|"uses list utilities"| node_libft
node_stack_header -->|"uses output API"| node_ft_printf

click node_sort_main "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/main.c"
click node_checker_main "https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_bonus.c"
click node_checker_io "https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_bonus.c"
click node_checker_apply "https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_bonus.c"
click node_checker_helpers "https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_utils_bonus.c"
click node_sort_core "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/sort.c"
click node_chunk_sort "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/chunk_sort.c"
click node_chunk_split "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/chunk_split.c"
click node_chunk_utils "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/chunk_utils.c"
click node_move "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/move.c"
click node_easy_sort "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_easy_sort.c"
click node_sort_three "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_sort_three.c"
click node_sort_asap "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_sort_asap.c"
click node_post_sort "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_post_sort.c"
click node_post_sort_utils "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_post_sort_utils.c"
click node_to_top "https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_to_the_top.c"
click node_stack_data "https://github.com/ulsgks/push_swap/blob/main/src/stack/data_mngt.c"
click node_stack_init "https://github.com/ulsgks/push_swap/blob/main/src/stack/stack_init.c"
click node_stack_utils "https://github.com/ulsgks/push_swap/blob/main/src/stack/stack_utils.c"
click node_stack_ops "https://github.com/ulsgks/push_swap/blob/main/src/stack/op_push.c"
click node_stack_rotate "https://github.com/ulsgks/push_swap/blob/main/src/stack/op_rotate.c"
click node_stack_reverse "https://github.com/ulsgks/push_swap/blob/main/src/stack/op_reverse_rotate.c"
click node_stack_swap "https://github.com/ulsgks/push_swap/blob/main/src/stack/op_swap.c"
click node_op_utils "https://github.com/ulsgks/push_swap/blob/main/src/stack/op_utils.c"
click node_stack_header "https://github.com/ulsgks/push_swap/blob/main/include/stack.h"
click node_push_header "https://github.com/ulsgks/push_swap/blob/main/include/push_swap.h"
click node_checker_header "https://github.com/ulsgks/push_swap/blob/main/include/checker_bonus.h"
click node_libft "https://github.com/ulsgks/push_swap/blob/main/lib/libft/include/libft.h"
click node_ft_printf "https://github.com/ulsgks/push_swap/blob/main/lib/ft_printf/include/ft_printf.h"

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_sort_main,node_checker_main,node_checker_io,node_checker_apply,node_checker_helpers,node_checker_header,node_user toneBlue
class node_sort_core,node_chunk_sort,node_chunk_split,node_chunk_utils,node_move,node_easy_sort,node_sort_three,node_sort_asap,node_post_sort,node_post_sort_utils,node_to_top,node_push_header toneAmber
class node_stack_data,node_stack_init,node_stack_utils,node_stack_ops,node_stack_rotate,node_stack_reverse,node_stack_swap,node_op_utils,node_stack_header toneMint
class node_libft,node_ft_printf toneRose
```

## Components

### Programs and validation

- [Push Swap CLI](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/main.c): `src/push_swap/main.c`
- [Checker CLI](https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_bonus.c): `src/checker_bonus/checker_bonus.c`
- [Read operations](https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_bonus.c): `src/checker_bonus/checker_bonus.c`
- [Apply and check](https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_bonus.c): `src/checker_bonus/checker_bonus.c`
- [Checker helpers](https://github.com/ulsgks/push_swap/blob/main/src/checker_bonus/checker_utils_bonus.c): `src/checker_bonus/checker_utils_bonus.c`
- [Checker interfaces](https://github.com/ulsgks/push_swap/blob/main/include/checker_bonus.h): `include/checker_bonus.h`

### Sorting algorithm

- [Sort orchestration](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/sort.c): `src/push_swap/sort.c`
- [Chunk sorting](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/chunk_sort.c): `src/push_swap/chunk_sort.c`
- [Chunk splitting](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/chunk_split.c): `src/push_swap/chunk_split.c`
- [Chunk utilities](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/chunk_utils.c): `src/push_swap/chunk_utils.c`
- [Chunk movement](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/move.c): `src/push_swap/move.c`
- [Easy-sort optimization](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_easy_sort.c): `src/push_swap/opti_easy_sort.c`
- [Three-item sorting](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_sort_three.c): `src/push_swap/opti_sort_three.c`
- [Early-sort optimization](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_sort_asap.c): `src/push_swap/opti_sort_asap.c`
- [Post-sort optimization](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_post_sort.c): `src/push_swap/opti_post_sort.c`
- [Optimization helpers](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_post_sort_utils.c): `src/push_swap/opti_post_sort_utils.c`
- [Chunk positioning](https://github.com/ulsgks/push_swap/blob/main/src/push_swap/opti_to_the_top.c): `src/push_swap/opti_to_the_top.c`
- [Sort interfaces](https://github.com/ulsgks/push_swap/blob/main/include/push_swap.h): `include/push_swap.h`

### Stack runtime

- [Stack lifecycle](https://github.com/ulsgks/push_swap/blob/main/src/stack/data_mngt.c): `src/stack/data_mngt.c`
- [Input validation and ranking](https://github.com/ulsgks/push_swap/blob/main/src/stack/stack_init.c): `src/stack/stack_init.c`
- [Stack queries](https://github.com/ulsgks/push_swap/blob/main/src/stack/stack_utils.c): `src/stack/stack_utils.c`
- [Stack operations](https://github.com/ulsgks/push_swap/blob/main/src/stack/op_push.c): `src/stack/op_push.c`
- [Rotation operations](https://github.com/ulsgks/push_swap/blob/main/src/stack/op_rotate.c): `src/stack/op_rotate.c`
- [Reverse rotations](https://github.com/ulsgks/push_swap/blob/main/src/stack/op_reverse_rotate.c): `src/stack/op_reverse_rotate.c`
- [Swap operations](https://github.com/ulsgks/push_swap/blob/main/src/stack/op_swap.c): `src/stack/op_swap.c`
- [Operation encoding](https://github.com/ulsgks/push_swap/blob/main/src/stack/op_utils.c): `src/stack/op_utils.c`
- [Stack interfaces](https://github.com/ulsgks/push_swap/blob/main/include/stack.h): `include/stack.h`

### Utility libraries

- [C utility functions](https://github.com/ulsgks/push_swap/blob/main/lib/libft/include/libft.h): `lib/libft/include/libft.h`
- [Formatted output](https://github.com/ulsgks/push_swap/blob/main/lib/ft_printf/include/ft_printf.h): `lib/ft_printf/include/ft_printf.h`

### Other components

- **CLI user**

## Connections

- CLI user → Push Swap CLI: provides input
- Push Swap CLI → Stack lifecycle: initializes data (evidence: `src/push_swap/main.c`)
- Push Swap CLI → Sort orchestration: sorts stacks (evidence: `src/push_swap/main.c`)
- Push Swap CLI → Operation encoding: prints operations (evidence: `src/push_swap/main.c`)
- Push Swap CLI → Stack lifecycle: frees data (evidence: `src/push_swap/main.c`)
- Stack lifecycle → Input validation and ranking: fills stack (evidence: `src/stack/data_mngt.c`)
- Input validation and ranking → C utility functions: parses numbers (evidence: `src/stack/stack_init.c`)
- Sort orchestration → Chunk sorting: dispatches sorting
- Chunk sorting → Chunk splitting: splits chunks
- Chunk sorting → Chunk utilities: uses chunk queries
- Chunk sorting → Chunk movement: moves elements
- Chunk sorting → Easy-sort optimization: optimizes small chunks
- Chunk sorting → Three-item sorting: sorts three items
- Chunk sorting → Early-sort optimization: reduces chunk work
- Chunk sorting → Chunk positioning: positions chunks
- Sort orchestration → Post-sort optimization: optimizes operations
- Post-sort optimization → Optimization helpers: uses helpers
- CLI user → Checker CLI: provides input
- Checker CLI → Stack lifecycle: initializes data (evidence: `src/checker_bonus/checker_bonus.c`)
- Checker CLI → Read operations: reads operations (evidence: `src/checker_bonus/checker_bonus.c`)
- Checker CLI → Apply and check: checks result (evidence: `src/checker_bonus/checker_bonus.c`)
- Apply and check → Checker helpers: applies operations (evidence: `src/checker_bonus/checker_bonus.c`)
- Read operations → Checker helpers: decodes operations (evidence: `src/checker_bonus/checker_bonus.c`)
- Apply and check → Stack operations: dispatches operations
- Stack interfaces → C utility functions: uses list utilities (evidence: `include/stack.h`)
- Stack interfaces → Formatted output: uses output API (evidence: `include/stack.h`)
