# shadin-t/minishell architecture

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

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

## Overview

1. **Overall shape**
   - This repo is a **single-process C shell application** with a mostly **monolithic implementation**.
   - `main.c` is the runtime core, `main.h` holds shared declarations, and `external_cmd.txt` is auxiliary content rather than a runtime subsystem.

2. **Primary architectural boundary**
   - The program sits between the **interactive terminal user** and the **Linux process/file-descriptor layer**.
   - It accepts command lines, interprets them, then either executes shell built-ins itself or spawns child processes for external commands.

3. **Input and command interpretation**
   - The first stage is **tokenization and parsing** of the raw input line.
   - The parser identifies command boundaries and features like:
     - command arguments
     - pipes (`|`)
     - input/output redirection
     - background execution (`&`)

4. **Dispatch model**
   - The shell likely has a **two-path execution model**:
     - **Built-in commands** handled inside the shell process
     - **External commands** executed through `fork` + `execvp`
   - This is a key architectural split because built-ins can change shell state, while external commands run in isolated child processes.

5. **Process management**
   - Each external command execution is mediated by **process creation and synchronization**.
   - The parent shell coordinates children using `wait`/`waitpid`-style behavior for foreground tasks, while background jobs return control to the prompt immediately.

6. **Pipes and command chaining**
   - Multi-command pipelines are implemented by connecting child processes with **Unix pipes**.
   - The shell builds a linear execution chain where one process’s stdout becomes the next process’s stdin.

7. **Redirection layer**
   - Input/output redirection is handled by manipulating **file descriptors** with `dup2` and file open/close calls.
   - This layer sits between parsing and execution, translating shell syntax into concrete stdin/stdout wiring for each child process.

8. **Signal handling boundary**
   - The shell explicitly manages terminal signals such as **Ctrl+C** and **Ctrl+Z**.
   - This is important architecturally because the shell must distinguish between the interactive parent and foreground children, especially during long-running commands.

9. **Data flow**
   - The runtime flow is: **terminal input → tokenization/parsing → execution plan → process setup/redirection/pipes → child execution → wait or background return**.
   - Output flows back through the terminal, while errors and signal events are handled by the shell’s control logic.

10. **Repository-level structure**
   - There is no evidence of a multi-module or layered service architecture here; it is a **compact training project** centered in one source file.
   - For an architecture diagram, model it as:
     - one interactive shell process
     - one parser/executor pipeline inside that process
     - multiple forked child processes for external commands
     - terminal, filesystem, and kernel syscalls as the external dependencies

Main entry points: [`main.c`](https://github.com/shadin-t/minishell/blob/main/main.c) (Exec planner), [`main.h`](https://github.com/shadin-t/minishell/blob/main/main.h) (Shared API), [`external_cmd.txt`](https://github.com/shadin-t/minishell/blob/main/external_cmd.txt) (Cmd notes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Shell runtime"]
  node_interactive_shell["Shell process<br/>runtime<br/>[main.c]"]
  node_input_loop["Read loop<br/>control flow<br/>[main.c]"]
  node_parser["Parser<br/>[main.c]"]
  node_builtin_dispatch["Built-ins<br/>dispatch<br/>[main.c]"]
  node_exec_planner["Exec planner<br/>execution<br/>[main.c]"]
  node_pipeline_builder["Pipelines<br/>[main.c]"]
  node_redir_manager[("Redirection<br/>fd wiring<br/>[main.c]")]
  node_process_manager["Process mgr<br/>process control<br/>[main.c]"]
  node_signal_handler(("Signals<br/>signal control<br/>[main.c]"))
  node_shared_api["Shared API<br/>declarations<br/>[main.h]"]
  node_cmd_notes["Cmd notes<br/>aux content<br/>[external_cmd.txt]"]
end

subgraph group_os["OS boundary"]
  node_terminal["Terminal<br/>interactive I/O"]
  node_fork_exec["Fork/exec<br/>syscalls"]
  node_pipe_fd[("Pipes<br/>fd syscalls")]
  node_wait_signals(("Wait/signals<br/>kernel control"))
  node_filesystem[("Filesystem")]
end

node_terminal -->|"input"| node_input_loop
node_input_loop -->|"scan"| node_parser
node_parser -->|"built-in"| node_builtin_dispatch
node_parser -->|"external"| node_exec_planner
node_exec_planner -->|"chain"| node_pipeline_builder
node_exec_planner -->|"redirect"| node_redir_manager
node_pipeline_builder -->|"pipe"| node_pipe_fd
node_redir_manager -->|"open"| node_filesystem
node_process_manager -->|"spawn"| node_fork_exec
node_process_manager -->|"sync"| node_wait_signals
node_signal_handler -->|"ctrl-c/z"| node_wait_signals
node_builtin_dispatch -->|"state"| node_interactive_shell
node_exec_planner -->|"run"| node_process_manager
node_interactive_shell -->|"trap"| node_signal_handler
node_shared_api -.->|"declares"| node_interactive_shell
node_cmd_notes -.->|"reference"| node_builtin_dispatch

click node_interactive_shell "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_input_loop "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_parser "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_builtin_dispatch "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_exec_planner "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_pipeline_builder "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_redir_manager "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_process_manager "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_signal_handler "https://github.com/shadin-t/minishell/blob/main/main.c"
click node_shared_api "https://github.com/shadin-t/minishell/blob/main/main.h"
click node_cmd_notes "https://github.com/shadin-t/minishell/blob/main/external_cmd.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_interactive_shell,node_input_loop,node_parser,node_builtin_dispatch,node_exec_planner,node_pipeline_builder,node_redir_manager,node_process_manager,node_signal_handler,node_shared_api,node_cmd_notes toneBlue
class node_terminal,node_fork_exec,node_pipe_fd,node_wait_signals,node_filesystem toneAmber
```

## Components

### Shell runtime

Single-process shell logic and its internal control flow

- [Shell process](https://github.com/shadin-t/minishell/blob/main/main.c): runtime · Interactive parent process that reads, interprets, and coordinates command execution · `main.c`
- [Read loop](https://github.com/shadin-t/minishell/blob/main/main.c): control flow · Prompts for input and drives each command cycle · `main.c`
- [Parser](https://github.com/shadin-t/minishell/blob/main/main.c): parse · Tokenizes command lines and detects syntax features such as pipes and redirection · `main.c`
- [Built-ins](https://github.com/shadin-t/minishell/blob/main/main.c): dispatch · Executes shell built-in commands inside the parent process · `main.c`
- [Exec planner](https://github.com/shadin-t/minishell/blob/main/main.c): execution · Builds the execution path for external commands and command chains · `main.c`
- [Pipelines](https://github.com/shadin-t/minishell/blob/main/main.c): pipeline · Connects commands into a Unix pipe chain · `main.c`
- [Redirection](https://github.com/shadin-t/minishell/blob/main/main.c): fd wiring · Applies input and output redirection using file descriptors · `main.c`
- [Process mgr](https://github.com/shadin-t/minishell/blob/main/main.c): process control · Forks children and coordinates foreground or background completion · `main.c`
- [Signals](https://github.com/shadin-t/minishell/blob/main/main.c): signal control · Handles interactive terminal signals such as interrupt and suspend · `main.c`
- [Shared API](https://github.com/shadin-t/minishell/blob/main/main.h): declarations · Common declarations and shared interfaces used by the shell code · `main.h`
- [Cmd notes](https://github.com/shadin-t/minishell/blob/main/external_cmd.txt): aux content · Supplementary command examples or notes, not part of the runtime path · `external_cmd.txt`

### OS boundary

Kernel and terminal facilities used by the shell

- **Terminal**: interactive I/O · User-facing stdin/stdout and prompt interaction
- **Fork/exec**: syscalls · Kernel process creation and program replacement for external commands
- **Pipes**: fd syscalls · Kernel pipe and file-descriptor operations for command chaining
- **Wait/signals**: kernel control · Process waiting and terminal signal delivery/handling
- **Filesystem**: files · Files opened for redirection and command I/O

## Connections

- Terminal → Read loop: input · User enters command lines through the terminal
- Read loop → Parser: scan · Each line is tokenized and interpreted
- Parser → Built-ins: built-in · Built-ins are routed to in-process handling
- Parser → Exec planner: external · External commands are prepared for child execution
- Exec planner → Pipelines: chain · Multi-command sequences are arranged into pipelines
- Exec planner → Redirection: redirect · Redirection is applied before launching children
- Pipelines → Pipes: pipe · Pipeline stages are connected through Unix pipes
- Redirection → Filesystem: open · Input and output files are opened for fd wiring
- Process mgr → Fork/exec: spawn · External commands run in forked child processes
- Process mgr → Wait/signals: sync · Foreground jobs are synchronized with wait-style behavior
- Signals → Wait/signals: ctrl-c/z · Interactive signals are mediated while jobs run
- Built-ins → Shell process: state · Built-ins mutate shell state in the parent process
- Exec planner → Process mgr: run · Planned commands are handed to process control
- Shell process → Signals: trap · The shell installs and manages terminal signal behavior
- Shared API → Shell process: declares · Main runtime code relies on shared declarations
- Cmd notes → Built-ins: reference · Auxiliary command content is related to command handling but not runtime logic