# thuggonaut/42ic_ring02_push_swap architecture

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

- Interactive diagram: https://gitdiagram.com/thuggonaut/42ic_ring02_push_swap
- Repository: https://github.com/thuggonaut/42ic_ring02_push_swap

## Overview

##### Project type and purpose
- This is a single‐executable, C‐based CLI tool for sorting a list of integers using two stacks (`a` and `b`) and a restricted set of operations (swap, push, rotate, reverse‐rotate).
- It includes a custom utility library (`libft`) and a suite of sorting routines (commands + algorithm orchestration).

##### File structure
- Top level:
- `Makefile` – build orchestration
- `push_swap` directory – source tree
- `libft` subdirectory – reusable helper functions (string, memory, I/O, linked-list)
- Under `push_swap/srcs`:
- `commands/` – implementations of the atomic operations
- `push_swap/` – orchestration: input handling, error checking, algorithm entry points (two main init routines: A→B, B→A)
- Header files under `inc/` declare stacks, nodes, and core APIs.
- Build artifacts flow: source → object files → final `push_swap` executable.

##### Pull extra insights from README
- Explains two modes of input: multiple args or single quoted string passed to `split()`
- Outlines the three sorting strategies: trivial swap (n=2), “sort_three” (n=3), and generic “Turk Algorithm” (>3)
- Emphasizes outputs of command sequences to stdout, later consumed by a visualizer or checker.

##### Main components
a. External CLI user input (shell)
b. Input parser & validator (split, string→long, duplicate/overflow checks)
c. Stack data structures: Stack A, Stack B (linked lists)
d. Command modules: swap.c, push.c, rotate.c, rev_rotate.c, sort_three.c
e. Algorithm controller (push_swap.c + init routines)
f. libft utility layer (memory, string, I/O, list ops)
h. External services (visualizer, checker) as optional consumers of stdout

##### Relationships & interactions
- User → CLI → Parser → Stack A
- Algorithm controller reads Stack A state → decides which command module to call
- Command module updates Stack A/B pointers → writes operation name to stdout
- Algorithm loops until Stack A is sorted and Stack B is empty
- libft functions are invoked by both parser (split, atoi), command modules (list node ops), and controller
- Makefile compiles all .c files (libft + push_swap) into the final executable

##### Architectural patterns/design principles
- Modular separation:
- Parser/validator
- Core algorithm (controller)
- Primitive operations (commands)
- Utility layer (libft)
- Single responsibility per module
- Data encapsulation: stacks as abstract linked lists with defined APIs
- Clear data flow: CLI → parser → model (stacks) → controller → primitives → output

##### Detailed elements
- Component names exactly as they appear in the code (e.g., `handle_errors.c`, `stack_utils.c`, `ft_lstadd_back`)
- Build process: from source dirs (`srcs/commands`, `srcs/push_swap`, `libft/src`) through Makefiles to the `push_swap` binary

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "CLI Interface"
        CLI["CLI User Input"]:::external
    end

    subgraph "Parser & Validator"
        Split["split.c"]:::parser
        HandleErrors["handle_errors.c"]:::parser
    end

    subgraph "Stack Data Structures"
        StackA["Stack A (linked list)"]:::data
        StackB["Stack B (linked list)"]:::data
        StackInit["stack_init.c"]:::data
        StackUtils["stack_utils.c"]:::data
        PSHeader["push_swap.h"]:::data
    end

    subgraph "Command Modules"
        Swap["swap.c"]:::commands
        PushCmd["push.c"]:::commands
        Rotate["rotate.c"]:::commands
        RevRotate["rev_rotate.c"]:::commands
        SortThree["sort_three.c"]:::commands
        SortStacks["sort_stacks.c"]:::commands
    end

    subgraph "Algorithm Controller"
        Controller["push_swap.c"]:::controller
        InitA["init_a_to_b.c"]:::controller
        InitB["init_b_to_a.c"]:::controller
    end

    subgraph "Libft Utilities"
        LibftInc["libft.h, get_next_line.h, ft_printf.h"]:::libft
        LibftSrc["libft src dir"]:::libft
    end

    subgraph "Build Process"
        RootMake["Root Makefile"]:::build
        PSMake["push_swap/Makefile"]:::build
        LibftMake["push_swap/libft/Makefile"]:::build
        Binary["push_swap Executable"]:::build
    end

    Visualizer["Visualizer/Checker"]:::external

    CLI -->|"args"| Split
    Split -->|"parsed args"| HandleErrors
    HandleErrors -->|"validated data"| StackA

    StackA -->|"initial state"| Controller
    Controller -->|"init A→B"| InitA
    Controller -->|"init B→A"| InitB

    Controller -->|"decide operation"| Swap
    Controller -->|"decide operation"| PushCmd
    Controller -->|"decide operation"| Rotate
    Controller -->|"decide operation"| RevRotate
    Controller -->|"decide operation"| SortThree
    Controller -->|"decide operation"| SortStacks

    Swap -->|"swap(a/b)"| StackA
    Swap -->|"swap(a/b)"| StackB
    PushCmd -->|"push(a/b)"| StackA
    PushCmd -->|"push(a/b)"| StackB
    Rotate -->|"rotate(a/b)"| StackA
    Rotate -->|"rotate(a/b)"| StackB
    RevRotate -->|"rev_rotate(a/b)"| StackA
    RevRotate -->|"rev_rotate(a/b)"| StackB
    SortThree -->|"sort 3 elements"| StackA
    SortStacks -->|"generic sort"| StackA & StackB

    Swap -->|"stdout op"| Visualizer
    PushCmd -->|"stdout op"| Visualizer
    Rotate -->|"stdout op"| Visualizer
    RevRotate -->|"stdout op"| Visualizer
    SortThree -->|"stdout ops"| Visualizer
    SortStacks -->|"stdout ops"| Visualizer

    Split -->|"ft_split, ft_atoi"| LibftInc
    HandleErrors -->|"ft_split, ft_atol"| LibftInc
    StackInit -->|"ft_lstinit"| LibftInc
    StackUtils -->|"ft_lst* ops"| LibftInc
    Swap -->|"ft_lst* ops"| LibftInc
    PushCmd -->|"ft_lst* ops"| LibftInc
    Rotate -->|"ft_lst* ops"| LibftInc
    RevRotate -->|"ft_lst* ops"| LibftInc
    Controller -->|"utility calls"| LibftInc

    RootMake --> PSMake
    RootMake --> LibftMake
    PSMake --> Binary
    LibftMake --> Binary

    click Split "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/push_swap/split.c"
    click HandleErrors "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/push_swap/handle_errors.c"
    click StackInit "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/push_swap/stack_init.c"
    click StackUtils "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/push_swap/stack_utils.c"
    click PSHeader "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/inc/push_swap.h"
    click Swap "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/commands/swap.c"
    click PushCmd "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/commands/push.c"
    click Rotate "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/commands/rotate.c"
    click RevRotate "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/commands/rev_rotate.c"
    click SortThree "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/commands/sort_three.c"
    click SortStacks "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/commands/sort_stacks.c"
    click Controller "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/push_swap/push_swap.c"
    click InitA "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/push_swap/init_a_to_b.c"
    click InitB "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/srcs/push_swap/init_b_to_a.c"
    click LibftInc "https://github.com/thuggonaut/42ic_ring02_push_swap/blob/main/push_swap/libft/inc/libft.h"
    click LibftSrc "https://github.com/thuggonaut/42ic_ring02_push_swap/tree/main/push_swap/libft/src/"
    click PSMake "https://github.com/thuggonaut/42ic_ring02_push_swap/tree/main/push_swap/Makefile"
    click LibftMake "https://github.com/thuggonaut/42ic_ring02_push_swap/tree/main/push_swap/libft/Makefile"
    click RootMake "https://github.com/thuggonaut/42ic_ring02_push_swap/tree/main/Makefile"

    classDef parser fill:#add8e6,stroke:#000
    classDef data fill:#90ee90,stroke:#000
    classDef commands fill:#ffa500,stroke:#000
    classDef controller fill:#d8bfd8,stroke:#000
    classDef libft fill:#d3d3d3,stroke:#000
    classDef build fill:#cccccc,stroke:#000
    classDef external fill:#f0f0f0,stroke:#000
```
