# zenix-s/push_swap architecture

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

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

## Overview

##### Project type and purpose
- Project Name: push_swap.
- Purpose: It is designed to sort a collection of numbers using a minimal number of operations by managing two stacks.
- The README is minimalist (only stating "# push_swap"), but the file structure indicates its focus on stack operations, error handling, argument parsing, and specialized sorting sequences. This is typical for push_swap challenges where efficiency and clear separation of concerns are key.

##### File structure
- Top-Level Structure: The project is organized under the "src" directory.
- Main Executable File: The entry point is located at src/push_swap.c with its corresponding header file src/push_swap.h.
- Sub-directories in src/app:
- case_sort: Contains specialized sorting algorithms for small cases (e.g., sort_three, sort_four, sort_five, bubble_sort).
- error_handlers: Contains functions to handle errors during execution.
- operators: Divided into "generic_operators" and specific operator functions (pa, pb, ra, rb, etc.) that perform stack operations.
- parse_args: Contains modules to validate and parse input arguments, load initial stacks, and process the input.
- sort: Contains the main sorting engine, sorting operations (cost evaluations, decision making, finding target values), and auxiliary tools (e.g., finding max, min, etc.).
- stack: Manages stack operations such as initialization and duplication checking.
- External Library: The directory src/lib/libft hints on reusable utility functions that assist with common tasks.

##### Components and their relationships
- Input/Argument Parser:
- Module: src/app/parse_args.
- Function: Validates and processes command-line arguments to initialize the data structures.
- Stack Manager:
- Module: src/app/stack.
- Function: Handles the core data structure (the stack), including initialization and verification (like duplicate checking).
- Sorting Engine:
- Module: src/app/sort and src/app/case_sort.
- Function: Determines if the stack is already sorted, chooses the appropriate sorting algorithm (using either generic sort or specialized algorithms for small cases), and calculates the cost of operations.
- Operators Module:
- Module: src/app/operators (including “generic_operators” for common stack operations and specific files for each operation – pa, pb, ra, etc.).
- Function: Execute operations on the stacks (pushing, swapping, rotating) based on sorting decisions.
- Error Handling:
- Module: src/app/error_handlers.
- Function: Handles improper states or invalid inputs.
- External Utilities:
- Module: src/lib/libft.
- Function: Provides common utility functions that the rest of the modules depend on.

a. Main Components:
- Argument Parser (src/app/parse_args)
- Stack Manager (src/app/stack)
- Sorting Engine (src/app/sort and src/app/case_sort)
- Operators (src/app/operators including generic operators and specific operator implementations)
- Error Handling (src/app/error_handlers)
- Utility Library (src/lib/libft)
b. Relationships/Interactions:
- From “Argument Parser” to “Stack Manager” (to show stack initialization).
- From “Stack Manager” to “Sorting Engine” (for checking current order and initiating sorting).
- Between “Sorting Engine” and “Operators” (highlighting how sorting decisions trigger operations).
- Error conditions routed from all major modules to “Error Handlers.”
- “Utility Library” should be depicted as an underlying support component feeding into most other modules.
c. Architectural Patterns / Design Principles:
- Separation of Concerns: Each module handles its dedicated functionality – parsing, sorting, stacks, etc.
- Modularity: Noting the separation of generic operations and specialized handling (for example, dedicated directories for different kinds of operators).
- Layered Approach: Input processing -> business logic (sorting decisions) -> action (operators execution) -> error handling.
d. Relevant Technologies and Libraries:
- C language constructs and system programming principles.
- Usage of a custom library (libft) which may include standard algorithms and utility functions.

##### Final Advice
- Be detailed – capture every major module and its sub-components.
- Don’t try to oversimplify: include as many key pieces (even the finer ones like cost evaluation components in the sorting module) to provide clarity.

## Diagram (Mermaid)

```mermaid
graph TD
    AP["Argument Parser"]:::module
    SM["Stack Manager"]:::module
    MSE["Main Sorting Engine"]:::module
    SCS["Small-case Sorting"]:::module
    OM["Operators Module"]:::module
    EH["Error Handlers"]:::error
    UL["Utility Library"]:::utility

    %% Data Flow between Components
    AP -->|"to init"| SM
    SM -->|"checks order"| MSE
    SM -->|"checks order"| SCS
    MSE -->|"triggers ops"| OM
    SCS -->|"triggers ops"| OM

    %% Error Handling connections (dashed red arrows)
    AP ---|"error"| EH
    SM ---|"error"| EH
    MSE ---|"error"| EH
    SCS ---|"error"| EH
    OM ---|"error"| EH

    %% Utility Library support (support arrows)
    UL -->|"supports"| AP
    UL -->|"supports"| SM
    UL -->|"supports"| MSE
    UL -->|"supports"| SCS
    UL -->|"supports"| OM

    %% Click Events
    click AP "https://github.com/zenix-s/push_swap/tree/main/src/app/parse_args"
    click SM "https://github.com/zenix-s/push_swap/tree/main/src/app/stack"
    click MSE "https://github.com/zenix-s/push_swap/tree/main/src/app/sort"
    click SCS "https://github.com/zenix-s/push_swap/tree/main/src/app/case_sort"
    click OM "https://github.com/zenix-s/push_swap/tree/main/src/app/operators"
    click EH "https://github.com/zenix-s/push_swap/tree/main/src/app/error_handlers"
    click UL "https://github.com/zenix-s/push_swap/tree/main/src/lib/libft"

    %% Styles
    classDef module fill:#b3d9ff,stroke:#007acc,stroke-width:2px;
    classDef error fill:#ffb3b3,stroke:#cc0000,stroke-width:2px;
    classDef utility fill:#ffffb3,stroke:#cccc00,stroke-width:2px;
```
