# flmarsou/minishell architecture

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

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

## Overview

##### Project type and purpose
- Minishell is a **CLI interpreter**—a small Unix-style shell that reads user commands, tokenizes and parses them (handling quotes, pipes, redirections, env variables), and then executes either internal builtins or external binaries via fork/exec.

##### File structure
- Top-level:
- includes/minishell.h – all shared data structures and function signatures
- src/main.c – shell entry point and REPL loop
- src/lexer – tokenization logic
- src/parser – syntax and semantics validation, command-structure building
- src/execution – fork/exec orchestration, pipe & redir handling, heredocs, signals
- src/builtins – implementations of cd, echo, env, exit, export, pwd, unset, execve wrapper
- src/utils & src/free & src/debug – string helpers, memory cleanup, logging/debug aids
- Makefile, LICENSE, git config—standard project metadata and build scripts.

##### README for additional insights
- The shell pipeline:
User input → Lexer (token list) → Parser (command struct with args, redirs, pipes) → Executor (create processes, set up pipes/redirs, dispatch builtins vs execve)
- Builtins run in-process (some may need to affect parent state, e.g. cd, exit).
- External commands use `fork()`, `execve()`.
- Supports here-docs, multi-stage pipelines, signal handling.

##### Main components
a. **User Interface / REPL**
– Reads input lines, handles special keys (not shown in code but implied), invokes Lexer
b. **Lexer**
– Tokenizer: produces sequence of tokens (WORD, QUOTE, PIPE, REDIR, DOLLAR…)
– Token counter and token list management
c. **Parser**
– Validates syntax (quotes matching, pipe placement, redir errors)
– Processes quotes, expands variables, merges WORD tokens
– Builds an internal **Command List**: each with argv[], list of redirections, pipe grouping
d. **Executor**
– **Pipeline Manager**: for N commands, allocates pipes, forks child processes
– **Redirection Handler**: opener/closer for <, >, >>, << (heredoc)
– **Signal Handlers**: in parent and children, special handling for heredoc and interrupted processes
– **Builtin Dispatcher**: detects if cmd matches one of {cd, echo…}, calls in-process function or bypasses to execve
– **External Command Launcher**: uses `execve()` to spawn binaries
e. **Environment State**
– A global map of environment variables, read by parser for `$VAR` expansion, modified by export/unset
f. **Utilities & Memory Management**
– Helper functions (string ops, errors)
– Free routines to clean up tokens, parse trees, child data

##### Relationships and data flow
- For each command node:
– Setup pipes ←→ Next command
– Apply redirections to STDIN/STDOUT
– If builtin → call function (possibly altering parent env)
– Else → fork & execve (child uses inherited env)

##### Architectural patterns and principles
- **Modular layers**: clear separation between lexing, parsing and execution
- **Pipeline pattern**: commands chained by pipes; each stage is a separate process
- **Command data structure**: similar to a simple AST—each node holds argv[], redir list
- **Single Responsibility**: each directory handles one aspect of the shell
- **In-process vs out-of-process**: builtins executed without fork when impacting parent state

##### Critical details to capture
- The loop in main.c (read-evaluate-print)
- How tokens flow into parser and get transformed
- The fork/pipe tree for pipelines
- Builtin handling in parent vs child
- Heredoc: temporary file or pipe, signal interception

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Layer"
        REPL["User Interface / REPL"]:::green
    end

    subgraph "Analysis Layer"
        LEXER["Lexer: tokenization"]:::green
        PARSER["Parser: syntax & var expansion"]:::green
    end

    subgraph "Execution Layer"
        EXEC["Executor: pipeline, redirs, heredoc, signals"]:::orange
        BUILTINS["Builtin Dispatcher & Implementations"]:::red
        ENVMAP["Environment State"]:::red
    end

    subgraph "Support Modules"
        UTILS["Utilities: string helpers, errors"]:::blue
        FREE["Memory Management & Cleanup"]:::blue
        DEBUG["Debugging & Logging Aids"]:::blue
    end

    OS["OS Kernel / System Calls"]:::grey

    %% Data flow
    REPL -->|"input string"| LEXER
    LEXER -->|"token list"| PARSER
    PARSER -->|"command structure"| EXEC

    %% Executor decisions and interactions
    EXEC -->|"[builtin]"| BUILTINS
    EXEC -->|"[external]"| OS
    EXEC -->|uses| ENVMAP
    ENVMAP -->|"$VAR expansions"| PARSER
    BUILTINS -->|modifies| ENVMAP

    %% Support usage
    UTILS --> LEXER
    UTILS --> PARSER
    UTILS --> EXEC
    FREE --> LEXER
    FREE --> PARSER
    FREE --> EXEC
    DEBUG --> LEXER
    DEBUG --> PARSER
    DEBUG --> EXEC

    %% Signals
    OS -.->|"signals"| EXEC

    %% Click Events
    click REPL "https://github.com/flmarsou/minishell/blob/main/src/main.c"
    click LEXER "https://github.com/flmarsou/minishell/tree/main/src/lexer"
    click PARSER "https://github.com/flmarsou/minishell/tree/main/src/parser"
    click EXEC "https://github.com/flmarsou/minishell/tree/main/src/execution"
    click BUILTINS "https://github.com/flmarsou/minishell/tree/main/src/builtins"
    click ENVMAP "https://github.com/flmarsou/minishell/blob/main/includes/minishell.h"
    click UTILS "https://github.com/flmarsou/minishell/tree/main/src/utils"
    click FREE "https://github.com/flmarsou/minishell/blob/main/src/free.c"
    click DEBUG "https://github.com/flmarsou/minishell/blob/main/src/debug.c"

    %% Styles
    classDef green fill:#ccf,stroke:#66f,color:#000
    classDef orange fill:#fc8,stroke:#f80,color:#000
    classDef red fill:#f88,stroke:#f44,color:#000
    classDef blue fill:#8cf,stroke:#08c,color:#000
    classDef grey fill:#ccc,stroke:#888,color:#000
```
