# achnouri/minishell-master architecture

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

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

## Overview

##### Project Type & Purpose
- This is a minimal Unix shell implementation in C (“Minishell”) whose goal is to replicate a subset of Bash features.
- It focuses on parsing user input, handling tokens, performing environment expansions, managing redirections and pipes, executing built-in and external commands, and handling signals and memory.

##### File Structure & Architectural Insights
- Top-level:
- Makefile – build orchestration
- includes/minishell.h – central declarations
- main.c – entry point
- Core modules under sources/:
- parser/ – tokenization, syntax validation, quote handling, expansions
– core_tokens/ – split input into tokens
– core_commands/ – detect redirections, pipes, heredoc
– core_expansions/ – expand environment variables
– shell_initialization – load env, set up signal handlers
- executer/ – execute commands
– builtins/ – cd, echo, env, exit, export, pwd, unset
– execution/ – fork/exec flow, waiting, exit codes
– redirection/ – file I/O, pipes
- shell_utils/ – memory management, error messages, libft support
- README confirms reliance on syscalls (fork, execve, dup2, pipe, wait), strict memory management, and signal handling.

##### Main Components
A. User Interface Layer
- Command-line prompt (readline or basic readline wrapper)
B. Parser Subsystem
1. Tokenizer (core_tokens)
2. Syntax Validator & Quote Handler (syntax_validator, quotes_utils)
3. Expander (core_expansions)
4. Command Builder (core_commands)
C. Execution Subsystem
1. Built-ins Handler (builtins modules)
2. External Command Launcher
3. Redirection Manager (io_file, pipe)
4. Process Manager (fork, execve, waitpid)
D. Environment Manager
- Tracks environment variables, provides lookup and update APIs
E. Signal Handler
- SIGINT, SIGQUIT, EOF behaviors
F. Memory Manager
- Allocation/free, garbage collection (gb_coll), libft utilities
G. OS Interface
- System calls invoked by subsystems

##### Component Interactions & Data Flow
1. User types a command → CLI layer
2. CLI → Parser: raw string passed to tokenizer → tokens list
3. Tokens → Expander: replace variables, handle quotes
4. Expanded tokens → Command Builder: detect pipes/redirections, build a command pipeline data structure
5. Built command structure → Executor:
a. Set up pipes and redirections via dup2/pipe
b. For each stage:
– If builtin, call in-process handler
– Else fork child → execve
c. Parent waits on child processes
6. Execution result → CLI prints exit status if needed → prompt returns
7. Throughout: Signal Handler intercepts Ctrl-C, Ctrl-D, Ctrl-\ and routes to CLI or child processes
8. Memory Manager allocates and frees all dynamic structures at each cycle

##### Architectural Patterns & Principles
- Modular separation: Parser vs Executor vs Utilities
- Single responsibility: each .c file handles one feature (tokenization, one builtin, one redirection case)
- Pipeline pattern: commands connected by Unix pipes
- Error-first and resource cleanup pattern: free on every failure path
- Minimal global state: environment stored in a managed structure

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    CLI["CLI Prompt & Main Loop"]:::cli
    click CLI "https://github.com/achnouri/minishell-master/blob/main/Project/main.c"

    %% Parser Subsystem
    subgraph "Parser Subsystem"
        direction TB
        Tokenizer["Tokenizer"]:::parser
        click Tokenizer "https://github.com/achnouri/minishell-master/tree/main/Project/sources/parser/core_tokens"
        SyntaxValidator["Syntax Validator & Quote Handler"]:::parser
        click SyntaxValidator "https://github.com/achnouri/minishell-master/blob/main/Project/sources/shell_utils/syntax_validator.c"
        click SyntaxValidator "https://github.com/achnouri/minishell-master/blob/main/Project/sources/shell_utils/quotes_utils.c"
        Expander["Expander"]:::parser
        click Expander "https://github.com/achnouri/minishell-master/tree/main/Project/sources/parser/core_expansions"
        CommandBuilder["Command Builder"]:::parser
        click CommandBuilder "https://github.com/achnouri/minishell-master/tree/main/Project/sources/parser/core_commands"
        ShellInit["Shell Initialization & Signal Setup"]:::parser
        click ShellInit "https://github.com/achnouri/minishell-master/blob/main/Project/sources/parser/shell_initialization.c"
    end

    %% Execution Subsystem
    subgraph "Execution Subsystem"
        direction TB
        Builtins["Built-in Commands Handler"]:::executor
        click Builtins "https://github.com/achnouri/minishell-master/tree/main/Project/sources/executer/builtins"
        ExternalLauncher["External Command Launcher & Process Manager"]:::executor
        click ExternalLauncher "https://github.com/achnouri/minishell-master/tree/main/Project/sources/executer/execution"
        RedirectionMgr["Redirection Manager"]:::executor
        click RedirectionMgr "https://github.com/achnouri/minishell-master/blob/main/Project/sources/executer/redirection/io_file.c"
        click RedirectionMgr "https://github.com/achnouri/minishell-master/blob/main/Project/sources/executer/redirection/pipe.c"
    end

    %% Shared Services
    EnvMgr["Environment Manager"]:::env
    click EnvMgr "https://github.com/achnouri/minishell-master/blob/main/Project/sources/parser/core_expansions/expander_env.c"
    SignalHandler["Signal Handler"]:::signal
    click SignalHandler "https://github.com/achnouri/minishell-master/blob/main/Project/sources/parser/shell_initialization.c"
    MemoryMgr["Memory Manager"]:::utils
    click MemoryMgr "https://github.com/achnouri/minishell-master/blob/main/Project/sources/shell_utils/free.c"

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

    %% Data Flows
    CLI -->|"raw input string"| Tokenizer
    Tokenizer -->|"token list"| SyntaxValidator
    SyntaxValidator -->|"validated tokens"| Expander
    Expander -->|"expanded tokens"| CommandBuilder
    CommandBuilder -->|"command AST"| Builtins
    CommandBuilder -->|"command AST"| ExternalLauncher
    CommandBuilder -->|"redirection plan"| RedirectionMgr
    Builtins -->|"in-process execution"| CLI
    ExternalLauncher -->|"fork/execve"| OS
    RedirectionMgr -->|"dup2/pipe"| OS
    ExternalLauncher -->|"waitpid"| CLI
    SignalHandler --> CLI
    SignalHandler --> ExternalLauncher
    MemoryMgr --> Tokenizer
    MemoryMgr --> CommandBuilder
    MemoryMgr --> ExternalLauncher
    EnvMgr --> Expander
    EnvMgr --> Builtins

    %% Styles
    classDef parser fill:#cce5ff,stroke:#004085,color:#004085
    classDef executor fill:#d4edda,stroke:#155724,color:#155724
    classDef utils fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef os fill:#fff3cd,stroke:#856404,color:#856404
    classDef cli fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef env fill:#fef2c0,stroke:#8a6d3b,color:#8a6d3b
    classDef signal fill:#f8d7da,stroke:#721c24,color:#721c24
```
