# ikardi69/minishell architecture

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

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

## Overview

##### Project type and purpose
- This is a minimal Unix‐style command‐line shell written in C (“Minishell”).
- Purpose: read user input, parse commands (including pipes, redirections, quotes, variables), execute built-ins or external programs, manage environment variables, and handle signals.

##### File structure
- Top‐level:
- main.c – entry point, loop invoking readline and dispatch
- /exec.h – shared type definitions (e.g., command nodes, env list)
- Makefile – build scripts
- Directories map to architectural modules:
- parsing/ – tokenization and syntax analysis
- execution/ – spawning processes, handling pipes & redirections
- builts/ – implementations of built-ins (cd, echo, env, exit, export, pwd, unset) and helper functions
- signal/ – custom signal handlers for Ctrl-C, Ctrl-\, Ctrl-D
- utils/ – miscellaneous helpers (environment list, here-doc, AST node management)
- README confirms use of readline, fork/execve, dup2, pipe, signal, environment syscalls, limited globals.

##### Extract architectural insights from README
- Core loop: prompt → readline → parse → expand (variables, quotes) → build command AST/list → execute
- Built-ins are invoked in-process; external commands spawn child via fork→execve
- Pipes chain child processes; redirections use dup2
- Single global variable holds signal status; most state is passed through function parameters or per-command structs
- Modules closely follow responsibilities: parsing, execution, built-ins, signals, utilities

##### Components
a. Main components:
1. CLI Interface module (main.c + readline)
2. Parser module (parsing/)
3. Expansion module (utils/env_utils.c + quote handling in parsing)
4. Command Model (AST or linked list of command structs from parsing/)
5. Execution Engine:
– Built-in Dispatcher (builts/)
– External Command Runner (execution/)
6. Environment Manager (utils/env_utils.c, creat_env, export_utils)
7. Signal Handler (signal/)
8. OS / Kernel (fork, execve, pipe, dup2, file/dir syscalls)
b. Relationships and interactions:
- User input flows into CLI Interface
- CLI → Parser → Command Model
- Command Model → Expansion (variable & quote) → final command structs
- Execution Engine examines each command struct:
- If built-in → Built-in Dispatcher
- Else → External Runner
- External Runner sets up pipes & redirections, forks children, calls execve
- Both Built-ins and External Runner read/write Environment Manager
- Signal Handler registered by main, intercepts Ctrl signals and notifies CLI/Execution Engine
- Execution Engine interacts with OS via system calls
c. Architectural patterns and principles:
- Modular separation: each directory is a single responsibility
- Pipeline pattern: commands linked in list for pipe chaining
- Dispatcher pattern: built-in vs external command selection
- Minimal global state: single global for signals; all else passed in structs
- Layered flow: Input → Parse/Expand → Execution → OS
d. Key technologies/libraries:
- readline (interactive prompt, history)
- Standard C libraries & POSIX syscalls (fork, execve, pipe, dup2, open, etc.)
- GNU Make build system

##### Final recommendations
- Explicitly show the shared Environment Manager being used at parse time and exec time
- Signal handling is drawn as an orthogonal component that can interrupt any stage

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI Module"
        CLI["CLI Interface\n(main.c)"]:::internal
    end

    subgraph "Parser Module"
        Parser["Parser\n(parsing/)"]:::internal
    end

    Expansion["Expansion Module\n(utils/env_utils.c)"]:::internal
    CommandModel["Command Model\n(utils/nodes_2.c\nutils/nodes_management.c)"]:::internal

    subgraph "Execution Engine"
        BuiltIn["Built-in Dispatcher\n(builts/)"]:::internal
        External["External Command Runner\n(execution/)"]:::exec
    end

    EnvMgr["Environment Manager\n(execution/creat_env.c\nutils/env_utils.c)"]:::internal
    Signal["Signal Handler\n(signal/signal_handler.c)"]:::signal
    OS["OS / Kernel\n(syscalls)"]:::os

    Makeflow["Makefile"]:::internal
    Types["Shared Types\n(include/exec.h)"]:::internal

    User["User"]:::external

    User -->|"input"| CLI
    CLI -->|"readline"| Parser
    Parser -->|"tokens/AST"| CommandModel
    Parser -->|"uses env"| Expansion
    Expansion -->|"expands vars/quotes"| CommandModel
    CommandModel -->|"dispatch"| BuiltIn
    CommandModel -->|"dispatch"| External
    BuiltIn -->|"access env"| EnvMgr
    External -->|"access env"| EnvMgr
    External -->|"fork+execve"| OS
    Signal -.->|"interrupt"| CLI
    Signal -.->|"interrupt"| BuiltIn
    Signal -.->|"interrupt"| External
    Types -->|"types"| Parser
    Types -->|"types"| BuiltIn
    Types -->|"types"| External

    click CLI "https://github.com/ikardi69/minishell/blob/main/main.c"
    click Parser "https://github.com/ikardi69/minishell/tree/main/parsing/"
    click Expansion "https://github.com/ikardi69/minishell/blob/main/utils/env_utils.c"
    click CommandModel "https://github.com/ikardi69/minishell/blob/main/utils/nodes_2.c"
    click BuiltIn "https://github.com/ikardi69/minishell/tree/main/builts/"
    click External "https://github.com/ikardi69/minishell/tree/main/execution/"
    click EnvMgr "https://github.com/ikardi69/minishell/blob/main/execution/creat_env.c"
    click EnvMgr "https://github.com/ikardi69/minishell/blob/main/utils/env_utils.c"
    click Signal "https://github.com/ikardi69/minishell/blob/main/signal/signal_handler.c"
    click Makeflow "https://github.com/ikardi69/minishell/tree/main/Makefile"
    click Types "https://github.com/ikardi69/minishell/blob/main/include/exec.h"

    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef exec fill:#90EE90,stroke:#333,stroke-width:1px
    classDef os fill:#FFA500,stroke:#333,stroke-width:1px
    classDef signal fill:#FF6347,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
