# fraqioui/minishell architecture

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

- Interactive diagram: https://gitdiagram.com/fraqioui/minishell
- Repository: https://github.com/fraqioui/minishell

## Overview

##### Main Components
- Input/Initialization Layer
- This module is responsible for initializing global structures (like the environment variables list) and saving stdin/stdout.
- It wraps the shell’s main loop and reads input using the readline function.
- Parsing Layer
- The “parser” directory implements functions for:
▪ Tokenizing the user input (using defined token types for pipes, redirections, logical operators, etc.).
▪ Handling syntax validations (ensuring quotes, parentheses, and redirections are well-formed).
▪ Re-ordering commands using the shunting yard algorithm to generate a proper list of tokens.
▪ Building an abstract syntax tree (AST) or command tree from the re-ordered tokens.
- Expansion Module
- Located under executor/expander and utils/tokenize, this module handles:
▪ Environment variable expansion.
▪ Special handling for wildcards (using the directory access routines and matching algorithm).
▪ Quote elimination and similar string processing before execution.
- Execution Layer
- Split between “executor/executor” and “executor/builtins,” this layer covers:
▪ Processing of logical operators (AND/OR) and pipes.
▪ Forking processes for non-builtin commands.
▪ Builtin command handling (cd, echo, env, export, unset, pwd, exit).
▪ Managing redirections and file descriptor duplication.
- Utility/Helper Functions
- Helpers in directories like utils/build, utils/libft, and utils/utils provide:
▪ Data structure building (e.g., command tree nodes).
▪ Custom printing (ft_printf) and various string/memory utilities.

##### Relationships and Interactions
- User Input flows into the Initialization component, which then passes the command string to the Parser.
- The Parser tokenizes, validates, re-orders, and builds the command tree (AST).
- The AST is then passed to the Executor:
- The Executor first checks for builtins; if the command is not a builtin, it will perform necessary expansions.
- The Execution layer then handles redirections, forks processes if needed, and finally calls execve for external commands.
- Utility modules support all layers by offering common functionalities that include token handling, error management, and memory utilities.

##### Architectural Patterns
- Layered Architecture: The design is separable into initialization, parsing, expansion, and execution layers.
- AST Construction: The shell uses the shunting yard algorithm to convert infix shell commands into an abstract syntax tree enabling recursive execution.
- Recursive Tree Evaluation: Execution is performed by recursively traversing the AST, processing operators (like “&&”, “||”, “|”) and individual commands.
- Modularity and Reuse: Helper functions and utility libraries (e.g., libft) ensure code reuse and cleaner separation of concerns.

##### Relevant Technologies/Frameworks
- C standard libraries for system calls (e.g., fork, execve, dup, chdir).
- Readline for user input.
- POSIX APIs for process management, pipe operations, and redirection.
- Custom libraries (libft, ft_printf) that provide support functions which are part of the overall architecture.

##### Detailed Steps for the Principal Software Engineer
1. User Input (readline) → Initialization.
2. Initialization → Parser:
▪ Tokenizer (handle quotes and syntax errors).
▪ Re-order command (applying shunting yard algorithm).
▪ AST/Tree Builder.
3. Parser → Expander:
▪ Environment variable expansion.
▪ Wildcard and quote removal.
4. Expander → Executor:
▪ Branching into Builtins vs. Forking for External Commands.
▪ Manage redirections, heredocs, and pipes.
5. Supporting Utilities work throughout to provide essential functions.
- Annotations for any module that implements a key algorithm (for the shunting yard algorithm and for wildcard matching).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    Z["User Input (readline)"]:::default

    %% Input/Initialization Layer
    subgraph "Input/Initialization Layer"
        A["Global Initialization"]:::init
        B["Initialization Helper"]:::init
    end

    %% Parsing Layer
    subgraph "Parsing Layer"
        C["Main Parser"]:::parsing
        D["Parser Core"]:::parsing
        E["Tokenizer"]:::parsing
        F["Syntax Checker"]:::parsing
        G["Re-order Commands"]:::parsing
        H["Signal Handler"]:::parsing
    end

    %% Expansion Module
    subgraph "Expansion Module"
        I["Expansion Core"]:::expansion
        J["Wildcard Handling"]:::expansion
        K["Wildcard Utilities"]:::expansion
        L["Tokenize Utils 1"]:::expansion
        M["Tokenize Utils 2"]:::expansion
    end

    %% Execution Layer
    subgraph "Execution Layer"
        %% External Commands
        subgraph "External Commands"
            N["Logical Operator Processor"]:::execution
            O["Command Executor"]:::execution
            P["Command Helper"]:::execution
            Q["Pipe Manager"]:::execution
            R["Redirection Helper"]:::execution
            S["Redirection Manager"]:::execution
            T["Startup Executor"]:::execution
        end
        %% Builtin Commands
        subgraph "Builtin Commands"
            U["Builtin Commands"]:::builtin
        end
    end

    %% Utility/Helper Functions
    subgraph "Utilities"
        V["Build Utilities"]:::util
        W["ft_printf Utilities"]:::util
        X["Libft Utilities"]:::util
        Y["General Utilities"]:::util
    end

    %% Main Flow
    Z -->|"reads input"| A
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    J --> K
    K --> L
    L --> M
    M -->|"passes expanded command"| N
    M ---->|"if builtin"| U
    N --> O
    O --> P
    P --> Q
    Q --> R
    R --> S
    S --> T

    %% Utilities support (dotted lines)
    A ---|"uses"| V
    C ---|"uses"| V
    I ---|"uses"| V
    N ---|"uses"| V

    %% Click Events
    click A "https://github.com/fraqioui/minishell/blob/main/parser/initialize.c"
    click B "https://github.com/fraqioui/minishell/blob/main/parser/initialize_hlp.c"
    click C "https://github.com/fraqioui/minishell/blob/main/parser/main.c"
    click D "https://github.com/fraqioui/minishell/blob/main/parser/parser.c"
    click E "https://github.com/fraqioui/minishell/blob/main/parser/tokenize.c"
    click F "https://github.com/fraqioui/minishell/blob/main/parser/syntax.c"
    click G "https://github.com/fraqioui/minishell/blob/main/parser/re_order.c"
    click H "https://github.com/fraqioui/minishell/blob/main/parser/signals.c"
    click I "https://github.com/fraqioui/minishell/blob/main/executor/expander/expanding.c"
    click J "https://github.com/fraqioui/minishell/blob/main/executor/expander/wildcard.c"
    click K "https://github.com/fraqioui/minishell/blob/main/executor/expander/wildcard_utils.c"
    click L "https://github.com/fraqioui/minishell/blob/main/utils/tokenize/tokenize_utils_1.c"
    click M "https://github.com/fraqioui/minishell/blob/main/utils/tokenize/tokenize_utils_2.c"
    click N "https://github.com/fraqioui/minishell/blob/main/executor/executor/and_or.c"
    click O "https://github.com/fraqioui/minishell/blob/main/executor/executor/cmd.c"
    click P "https://github.com/fraqioui/minishell/blob/main/executor/executor/cmd_helper.c"
    click Q "https://github.com/fraqioui/minishell/blob/main/executor/executor/pipe.c"
    click R "https://github.com/fraqioui/minishell/blob/main/executor/executor/redir_hlp.c"
    click S "https://github.com/fraqioui/minishell/blob/main/executor/executor/redirections.c"
    click T "https://github.com/fraqioui/minishell/blob/main/executor/executor/start.c"
    click U "https://github.com/fraqioui/minishell/tree/main/executor/builtins/"
    click V "https://github.com/fraqioui/minishell/tree/main/utils/build/"
    click W "https://github.com/fraqioui/minishell/tree/main/utils/ft_printf/"
    click X "https://github.com/fraqioui/minishell/tree/main/utils/libft/"
    click Y "https://github.com/fraqioui/minishell/tree/main/utils/utils/"

    %% Styles
    classDef init fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef parsing fill:#ABEBC6,stroke:#145A32,stroke-width:2px;
    classDef expansion fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef execution fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef builtin fill:#D98880,stroke:#C0392B,stroke-width:2px;
    classDef util fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef default fill:#F0F0F0,stroke:#333,stroke-width:2px;
```
