# moraouid/minishell architecture

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

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

## Overview

##### Project type and purpose
- Type: A command-line shell (an interpreter) written in C.
- Purpose: Read user input, parse it into commands, handle expansions/redirections/pipelines/built-ins, invoke external programs or built-ins, and manage resources/signals like a minimal Bash clone.

##### High-level module breakdown (from file tree / README)
- Entry & Loop:
– minishell.c + readline integration (GNU Readline)
- Parsing & Syntax:
– parse/tokeniziation → split raw input
– parse/parsing → build command structures & validate
– parse/expansions → variable and status expansion
– parse/remove_quotes → strip quote characters
– parse/syntax_errors → report errors
- Execution Engine:
– exec/exec.c + exec_utils* → fork/exec, pipeline wiring
– exec/redirect_utils.c → file-descriptor redirections
– herdoc/ → heredoc delimiter handling
- Built-ins:
– builtins/my_*.c → cd, echo, pwd, env, export, unset, exit
– builtins/my_utils*.c → shared routines for built-ins
- Helpers & Utils:
– helper_utils → string split, environment copy, memory-tracking GC, misc utils
- Signal Handling:
– signal/signal.c → SIGINT, SIGQUIT, EOF behavior
- Interfaces & Data:
– includes/*.h → public interfaces for parse, exec, overall shell APIs

##### Key architectural patterns
- Pipeline of responsibility (“stages”): Input → Tokenization → Parsing → Expansion → Quote Removal → Execution
- Master loop with resource-cleanup at each iteration via a simple GC tracker
- Parent vs. child process distinction for built-ins vs. external commands
- Use of POSIX APIs (fork, execve, pipe, dup2, wait) and GNU Readline library

##### Main components & their interactions

A. User Interface Layer
- Responsibilities: display prompt, read user input, history
- Tech: GNU Readline

B. Frontend (Parsing Pipeline)
1. Tokenizer
– Input: raw line string
– Output: list of tokens (words, operators)
2. Parser & AST Builder
– Input: tokens
– Output: command data structures (linked lists or trees)
3. Expander
– Input: command structures with $VAR, $?
– Output: substituted strings, possibly splitting tokens
4. Quote Remover
– Input: expanded tokens with quotes
– Output: final argv[] lists
5. Syntax/Error Checker
– Hooks into parser to enforce valid operator usage

C. Execution Engine
1. Built-in Dispatcher
– Directly executed in parent for state-changing built-ins (cd, export, unset, exit)
2. External Command Runner
– Uses fork()+execve(), PATH lookup via helper_utils copy_env
3. Pipeline Manager
– Orchestrates pipe() creation, fd wiring
4. Redirection Manager
– Handles <, >, >> by opening files and dup2()
5. Heredoc Handler
– Reads until delimiter, writes to temporary FD and wires as stdin

D. Shared Services
- Environment Manager (copy_env.c, my_env.c, my_export.c, my_unset.c)
- Memory Tracker / GC (gc.c)
- Signal Handler (signal.c)

E. OS Interface
- System calls: fork, execve, pipe, dup2, open, close, wait, signal APIs

- From those to “Pipeline Manager” / “Redirection Manager” / “Heredoc Handler”

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI Layer"
        Readline["Readline Interface"]:::io
    end

    subgraph "Parsing Pipeline"
        tokens["Tokenizer"]:::parse
        parser["Parser & AST Builder"]:::parse
        expander["Expander"]:::parse
        quoteRemover["Quote Remover"]:::parse
        syntax["Syntax/Error Checker"]:::parse
    end

    subgraph "Execution Engine"
        dispatcher["Built-in Dispatcher"]:::exec
        external["External Command Runner"]:::exec
        pipeline["Pipeline & External Runner"]:::exec
        redirect["Redirection Manager"]:::exec
        heredoc["Heredoc Handler"]:::exec
    end

    subgraph "Shared Services"
        envmgr["Environment Manager"]:::util
        gc["Memory Tracker / GC"]:::util
        helpers["General Helpers & Utils"]:::util
        signal["Signal Handler"]:::util
    end

    os["OS Interface (syscalls)"]:::os

    Readline -->|raw input| tokens
    tokens --> parser
    parser --> expander
    expander --> quoteRemover
    quoteRemover --> syntax
    syntax -->|"command structures"| dispatcher
    syntax -->|"command structures"| external
    dispatcher --> pipeline
    external --> pipeline
    pipeline --> redirect
    pipeline --> heredoc
    dispatcher --> envmgr
    external --> envmgr

    tokens -.-> gc
    parser -.-> gc
    expander -.-> gc
    quoteRemover -.-> gc
    syntax -.-> gc
    dispatcher -.-> gc
    external -.-> gc
    pipeline -.-> gc
    redirect -.-> gc
    heredoc -.-> gc

    Readline -->|signals| signal
    signal --> Readline
    signal --> dispatcher
    signal --> external

    envmgr --> os
    gc --> os
    helpers --> dispatcher
    helpers --> external
    helpers --> tokens

    click Readline "https://github.com/moraouid/minishell/blob/main/minishell.c"
    click tokens "https://github.com/moraouid/minishell/blob/main/parse/tokeniziation/tokeniziation.c"
    click tokens "https://github.com/moraouid/minishell/blob/main/parse/tokeniziation/tokeniziation_help.c"
    click parser "https://github.com/moraouid/minishell/blob/main/parse/parsing.c"
    click parser "https://github.com/moraouid/minishell/blob/main/parse/parsing_utils.c"
    click parser "https://github.com/moraouid/minishell/blob/main/parse/creat_command.c"
    click expander "https://github.com/moraouid/minishell/blob/main/parse/expansions/expansions.c"
    click expander "https://github.com/moraouid/minishell/blob/main/parse/expansions/expand_help.c"
    click expander "https://github.com/moraouid/minishell/blob/main/parse/expansions/expand_utils.c"
    click expander "https://github.com/moraouid/minishell/blob/main/parse/expansions/split_after_expand.c"
    click quoteRemover "https://github.com/moraouid/minishell/blob/main/parse/remove_quotes/remove_quotes.c"
    click quoteRemover "https://github.com/moraouid/minishell/blob/main/parse/remove_quotes/remove_expand_quotes.c"
    click syntax "https://github.com/moraouid/minishell/blob/main/parse/syntax_errors.c"
    click dispatcher "https://github.com/moraouid/minishell/blob/main/builtins/my_cd.c"
    click dispatcher "https://github.com/moraouid/minishell/blob/main/builtins/my_utils.c"
    click external "https://github.com/moraouid/minishell/blob/main/exec/exec.c"
    click external "https://github.com/moraouid/minishell/blob/main/exec/exec_utils.c"
    click external "https://github.com/moraouid/minishell/blob/main/exec/exec_utils2.c"
    click external "https://github.com/moraouid/minishell/blob/main/exec/exec_utils3.c"
    click pipeline "https://github.com/moraouid/minishell/blob/main/helper_utils/copy_env.c"
    click redirect "https://github.com/moraouid/minishell/blob/main/exec/redirect_utils.c"
    click heredoc "https://github.com/moraouid/minishell/blob/main/herdoc/heredoc.c"
    click heredoc "https://github.com/moraouid/minishell/blob/main/herdoc/heredoc_utils.c"
    click heredoc "https://github.com/moraouid/minishell/blob/main/herdoc/heredoc_utils2.c"
    click envmgr "https://github.com/moraouid/minishell/blob/main/helper_utils/copy_env.c"
    click gc "https://github.com/moraouid/minishell/blob/main/helper_utils/gc.c"
    click helpers "https://github.com/moraouid/minishell/blob/main/helper_utils/ft_split.c"
    click signal "https://github.com/moraouid/minishell/blob/main/signal/signal.c"
    click os "https://github.com/moraouid/minishell/blob/main/includes/minishell.h"

    classDef parse fill:#ADD8E6,stroke:#000;
    classDef exec fill:#90EE90,stroke:#000;
    classDef io fill:#FFD700,stroke:#000;
    classDef util fill:#D3D3D3,stroke:#000;
    classDef os fill:#FFA500,stroke:#000;
```
