# driely01/minishell architecture

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

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

## Overview

##### Project Type and Purpose
- This is a C-based CLI application implementing a mini-bash shell.
- It reads user commands, tokenizes and parses them, handles built-in commands (cd, echo, export, unset, pwd, exit, env, heredoc) and external commands.
- It uses POSIX system calls (fork, execve, pipe, dup2, wait, open/read/close, chdir, getcwd, etc.) for process control and I/O redirection.

##### File Structure Analysis
- Top-level:
- minishell.c / minishell.h – entry point and global definitions
- Makefile / README.md
- Directories (modules):
- builtin/ – implementations of built-in commands (cd, echo, exit, export, pwd, unset)
- parcing/ – (sic) lexical analysis and syntax checking of the input line
- expand/ – variable expansion, quote removal, wildcard handling
- execution/ – process creation, piping, redirections, signal handling
- utils/ – shared helper functions (string ops, list management, error handling)

##### README Insights
- Contains an overview of parsing/tokenizing flow
- Emphasizes system calls used and the need to mirror bash behavior
- Mentions two major phases: parsing (tokenize → syntax check) and execution (handle pipes, redirections, built-ins, external commands, heredoc)

##### Main Components
a. User Interface Layer
- “Terminal / stdin” → Command line reader
b. Parsing Layer
- Tokenizer (scans input char-by-char → tokens)
- Syntax Checker (validates token sequence, brackets, separators)
c. Expansion Layer
- Variable & parameter expansion
- Quote stripping
- Wildcard (globbing) expansion
d. Execution Dispatcher
- Distinguishes built-in vs external commands
- Manages command sequence and pipelines
e. Built-in Module
- cd, pwd, echo, export, unset, exit, env, heredoc controllers
- Interacts with environment data structure in memory
f. External Command Module
- fork → child process
- execve → load external binary
g. I/O & Pipe Manager
- pipe() / dup2() for stdin/stdout redirection
- open()/close() for file redirections
h. Process and Signal Controller
- wait()/waitpid() for child synchronization
- signal() / kill() handlers for SIGINT, SIGQUIT
i. Environment Store
- In-memory list of key=value pairs (export/unset)
j. OS Kernel (external service)
- System calls interface

##### Relationships & Data Flow
- Terminal → Tokenizer
- Tokenizer → Parser → Expander → Dispatcher
- Dispatcher → Built-in Module (no fork) ↔ Environment Store → return status
- Dispatcher → External Module (fork + execve) → Kernel
- Kernel → process image + file system
- Dispatcher → I/O & Pipe Manager → Kernel
- All modules use Utils library for common functions
- Bidirectional data flow where appropriate (e.g., built-ins modify environment).

##### Key Architectural Patterns
- Modular pipeline: clear separation of concerns (Lexing, Parsing, Expansion, Execution)
- Single process orchestrator + forked children for external commands
- Shared global environment state for built-ins
- POSIX system call façade for kernel interactions

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    Terminal["Terminal / stdin"]:::ui
    Reader["Command Reader"]:::ui

    %% Parsing Layer
    subgraph "Parsing Layer"
        Tokenizer["Tokenizer\n(lexical analysis)"]:::internal
        Parser["Syntax Checker"]:::internal
    end

    %% Expansion Layer
    subgraph "Expansion Layer"
        Expander["Expander\n(var, quotes, glob)"]:::internal
    end

    %% Execution Dispatcher
    Dispatcher["Execution Dispatcher"]:::internal

    %% Built-in Module
    subgraph "Built-in Module"
        Builtins["Built-in Commands"]:::builtin
    end

    %% External Command Module
    External["External Command Module"]:::external

    %% I/O & Pipe Manager
    IOManager["I/O & Pipe Manager"]:::internal

    %% Process and Signal Controller
    Signals["Process & Signal Controller"]:::internal

    %% Environment Store
    EnvStore["Environment Store"]:::builtin

    %% Utility Library
    Utils["Utils Library"]:::util

    %% OS Kernel
    Kernel["OS Kernel (syscalls)"]:::kernel

    %% Connections
    Terminal --> Reader
    Reader --> Tokenizer
    Tokenizer --> Parser
    Parser --> Expander
    Expander --> Dispatcher
    Dispatcher --> Builtins
    Dispatcher --> External
    Dispatcher --> IOManager
    Dispatcher --> Signals
    Builtins --> EnvStore
    External --> Kernel
    IOManager --> Kernel
    Signals --> Kernel

    %% Utils dependencies (dotted)
    Tokenizer -.-> Utils
    Parser -.-> Utils
    Expander -.-> Utils
    Dispatcher -.-> Utils
    Builtins -.-> Utils
    External -.-> Utils
    IOManager -.-> Utils
    EnvStore -.-> Utils

    %% Click Events
    click Terminal "https://github.com/driely01/minishell/blob/main/minishell.c"
    click Tokenizer "https://github.com/driely01/minishell/tree/main/parcing/"
    click Parser "https://github.com/driely01/minishell/blob/main/parcing/syntax_error.c"
    click Expander "https://github.com/driely01/minishell/tree/main/expand/"
    click Dispatcher "https://github.com/driely01/minishell/blob/main/execution/execution.c"
    click IOManager "https://github.com/driely01/minishell/tree/main/execution/"
    click Signals "https://github.com/driely01/minishell/blob/main/execution/signals.c"
    click Builtins "https://github.com/driely01/minishell/tree/main/builtin/"
    click EnvStore "https://github.com/driely01/minishell/blob/main/builtin/export/env_variables.c"
    click Utils "https://github.com/driely01/minishell/tree/main/utils/"

    %% Styles
    classDef ui fill:#dae8fc,stroke:#6c8ebf,color:#000;
    classDef internal fill:#bdd7ee,stroke:#3a6ea5,color:#000;
    classDef builtin fill:#d9ead3,stroke:#6aa84f,color:#000;
    classDef external fill:#fce5cd,stroke:#e69138,color:#000;
    classDef util fill:#f2f2f2,stroke:#999999,color:#000,stroke-dasharray: 5 5;
    classDef kernel fill:#f4cccc,stroke:#cc4125,color:#000;
```
