# hel-asli/minishell architecture

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

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

## Overview

##### Project type and purpose
- This is a command-line shell written in C (“Minishell”), not a web or distributed system.
- It acts as an interactive interpreter: it reads user input, parses it, expands variables and wildcards, handles built-in commands, forks external processes, manages redirections and pipes, and returns results.

##### File structure
- Top level:
- main.c – entry point, initializes shell, sets up signal handlers, loops reading input.
- minishell.h – shared type definitions, constants, function prototypes.
- Directories:
- parsing/ – handles lexing, syntax checking, quote handling, wildcard expansion, here-docs.
- execution/ – runs parsed commands: built-in dispatcher, fork/exec logic, redirections, pipes.
- builtins/ – implementation of built-in commands (cd, echo, env, export, unset, pwd, exit).
- utils/ – string and list helpers, error/reporting, environment‐variable list utilities.
- xtra/ – tests, edge-cases, TODOs (not part of runtime).
- Config/build: Makefile, .gitignore.
- External dependency: GNU Readline (for prompt and history).

##### Key README insights
- Follows Bash behavior for quotes, expansions, redirections, pipes, signals (CTRL-C/D/\\).
- Implements prompt with history, PATH lookup, environment variable expansion, wildcard *, exit status ($?).

##### Final advice
- Major phases: input, parsing, expansion, execution, result.
- Do not omit signal flow or environment interactions.
- The end result should give any engineer a clear overview of how a command travels through the shell’s architecture from keystroke to process execution and back.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interfaces
    User["User & Terminal"]:::external
    Readline["Readline Module"]:::external
    OS["OS Kernel"]:::external

    %% Internal Modules
    Main["Main"]:::internal
    Shared["Shared Definitions & Data Structures"]:::internal
    Utils["Utility Module"]:::internal

    subgraph "Parser Module"
        ParserCore["Core Parser"]:::internal
        Lex["Lexer & Tokenization"]:::internal
        Syntax["Syntax Checker"]:::internal
        Quote["Quote Handler"]:::internal
        Wildcard["Wildcard Expander"]:::internal
        Heredoc["Here-Document Handler"]:::internal
    end

    AST["Command AST / Data Structures"]:::data

    subgraph "Executor Module"
        ExecOrch["Execution Orchestration"]:::internal
        Dispatch["Built-in vs External Dispatcher"]:::internal
        External["External Command Launcher"]:::internal
        Redirect["Redirection Handler"]:::internal
        Pipe["Pipe & Helper Functions"]:::internal
    end

    subgraph "Built-ins Module"
        CD["cd"]:::internal
        Echo["echo"]:::internal
        EnvB["env"]:::internal
        ExitB["exit"]:::internal
        Export["export"]:::internal
        Pwd["pwd"]:::internal
        Unset["unset"]:::internal
    end

    EnvStore["Environment Store"]:::data
    Signals["Signal Handler"]:::internal

    %% Data & Control Flows
    User --> Readline
    Readline --> Main
    Readline --> Signals
    Signals --> Readline
    Signals --> ExecOrch

    Main --> ParserCore
    Shared -.-> Main
    Shared -.-> ParserCore

    ParserCore --> Lex
    ParserCore --> Syntax
    ParserCore --> Quote
    ParserCore --> Wildcard
    ParserCore --> Heredoc
    ParserCore --> AST

    Lex --> AST
    Syntax --> AST
    Quote --> AST
    Wildcard --> AST
    Heredoc --> AST

    AST --> ExecOrch
    ExecOrch --> Dispatch
    Dispatch --> CD
    Dispatch --> Echo
    Dispatch --> EnvB
    Dispatch --> ExitB
    Dispatch --> Export
    Dispatch --> Pwd
    Dispatch --> Unset
    Dispatch --> External

    CD --> EnvStore
    Echo --> EnvStore
    EnvB --> EnvStore
    ExitB --> EnvStore
    Export --> EnvStore
    Pwd --> EnvStore
    Unset --> EnvStore

    ExecOrch --> Redirect
    ExecOrch --> Pipe
    ExecOrch --> EnvStore
    ExecOrch --> OS
    Redirect --> OS
    Pipe --> OS

    OS --> ExecOrch
    ExecOrch -->|"exit status"| EnvStore

    Utils -.-> ParserCore
    Utils -.-> ExecOrch
    Utils -.-> CD
    Utils -.-> Echo
    Utils -.-> EnvB
    Utils -.-> ExitB
    Utils -.-> Export
    Utils -.-> Pwd
    Utils -.-> Unset

    %% Click Events
    click Main "https://github.com/hel-asli/minishell/blob/main/main.c"
    click Shared "https://github.com/hel-asli/minishell/blob/main/minishell.h"
    click ParserCore "https://github.com/hel-asli/minishell/blob/main/parsing/parsing.c"
    click Lex "https://github.com/hel-asli/minishell/blob/main/parsing/parsing.c"
    click Syntax "https://github.com/hel-asli/minishell/blob/main/parsing/syntax_check.c"
    click Quote "https://github.com/hel-asli/minishell/blob/main/parsing/parsing_helper.c"
    click Wildcard "https://github.com/hel-asli/minishell/blob/main/parsing/wildcard.c"
    click Heredoc "https://github.com/hel-asli/minishell/blob/main/parsing/heredoc.c"
    click Signals "https://github.com/hel-asli/minishell/blob/main/parsing/signals.c"
    click ExecOrch "https://github.com/hel-asli/minishell/blob/main/execution/execution.c"
    click Dispatch "https://github.com/hel-asli/minishell/blob/main/execution/execution_helper.c"
    click External "https://github.com/hel-asli/minishell/blob/main/execution/exec.c"
    click Redirect "https://github.com/hel-asli/minishell/blob/main/execution/redirection.c"
    click Pipe "https://github.com/hel-asli/minishell/blob/main/execution/helper_functions.c"
    click CD "https://github.com/hel-asli/minishell/blob/main/builtins/cd.c"
    click Echo "https://github.com/hel-asli/minishell/blob/main/builtins/echo.c"
    click EnvB "https://github.com/hel-asli/minishell/blob/main/builtins/env.c"
    click ExitB "https://github.com/hel-asli/minishell/blob/main/builtins/exit.c"
    click Export "https://github.com/hel-asli/minishell/blob/main/builtins/export.c"
    click Pwd "https://github.com/hel-asli/minishell/blob/main/builtins/pwd.c"
    click Unset "https://github.com/hel-asli/minishell/blob/main/builtins/unset.c"
    click EnvStore "https://github.com/hel-asli/minishell/blob/main/utils/env.utils.c"
    click Utils "https://github.com/hel-asli/minishell/tree/main/utils/"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#2980B9,color:#1B2631
    classDef external fill:#ABEBC6,stroke:#229954,color:#1B2631
    classDef data fill:#F9E79F,stroke:#B7950B,color:#1B2631
```
