# mahakagarwal7/os-shell architecture

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

- Interactive diagram: https://gitdiagram.com/mahakagarwal7/os-shell
- Repository: https://github.com/mahakagarwal7/os-shell

## Overview

#### Purpose and Entry Point
This repository implements a small Unix-like shell for learning OS process and parsing concepts. The user-facing entry point is `msh.sh`, which orchestrates shell startup, input handling, parsing, built-ins, and command execution.

#### Shell Orchestration
`msh.sh` is the top-level control loop. It likely sources the shell libraries, reads commands interactively, dispatches built-in commands, and delegates external commands to the execution layer.

Paths: `msh.sh`, `lib/utils.sh`

#### Parsing Boundary
Command-line parsing is split between shell integration and native code. The shell-facing parser wrapper lives in `lib/parser.sh`; C parsing interfaces and implementation are defined by `include/parser.h` and `c_src/parser.c`. This establishes a native parsing boundary rather than implementing all tokenization in Bash.

Paths: `lib/parser.sh`, `include/parser.h`, `c_src/parser.c`

#### Built-in Command Handling
Commands that must affect shell process state, such as directory or environment-oriented operations, belong in the built-in layer rather than being forked as external programs. `lib/builtin.sh` is the dedicated dispatch/implementation boundary for these commands.

Paths: `lib/builtin.sh`, `msh.sh`

#### External Process Execution
External commands are delegated to an executor layer. `lib/executor.sh` provides shell-level execution coordination, while `c_src/fork_exec.c` contains native process-management logic, likely centered on `fork`/`exec` behavior. This separation is the core OS-runtime boundary: built-ins execute in the shell process; external commands execute in child processes.

Paths: `lib/executor.sh`, `c_src/fork_exec.c`

#### Native Interface and Runtime Dependencies
The project combines Bash scripts with C code compiled against Unix/POSIX process APIs. The C layer exposes parser functionality through `include/parser.h` and implements process launching in `c_src/fork_exec.c`. Its material runtime dependency is a Unix-like environment supporting shell execution and POSIX process primitives.

Paths: `include/parser.h`, `c_src/parser.c`, `c_src/fork_exec.c`

#### Primary Control Flow
A command flows from `msh.sh` into parsing via `lib/parser.sh` and the C parser. The resulting command classification determines whether it is handled by `lib/builtin.sh` in-process or sent through `lib/executor.sh` to the native fork/exec implementation. Utility functions shared across these stages are centralized in `lib/utils.sh`.

Paths: `msh.sh`, `lib/parser.sh`, `lib/builtin.sh`

Main entry points: [`msh.sh`](https://github.com/mahakagarwal7/os-shell/blob/main/msh.sh) (Shell control loop), [`c_src/parser.c`](https://github.com/mahakagarwal7/os-shell/blob/main/c_src/parser.c) (Native parser), [`c_src/fork_exec.c`](https://github.com/mahakagarwal7/os-shell/blob/main/c_src/fork_exec.c) (Fork/exec runtime), [`lib/parser.sh`](https://github.com/mahakagarwal7/os-shell/blob/main/lib/parser.sh) (Parser wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Bash shell"]
  node_msh["Shell control loop<br/>Bash entry point<br/>[msh.sh]"]
  node_utils["Shared utilities<br/>Bash library<br/>[utils.sh]"]
  node_parser_wrapper["Parser wrapper<br/>Bash library<br/>[parser.sh]"]
  node_builtin["Built-in commands<br/>Bash dispatch<br/>[builtin.sh]"]
  node_executor["External executor<br/>Bash coordinator<br/>[executor.sh]"]
end

subgraph group_native["Native process layer"]
  node_parser_header["Parser interface<br/>C header<br/>[parser.h]"]
  node_parser_c["Native parser<br/>C implementation<br/>[parser.c]"]
  node_fork_exec["Fork/exec runtime<br/>C process launcher<br/>[fork_exec.c]"]
end

node_user(("Shell user<br/>actor"))
node_posix{{"Unix/POSIX runtime<br/>runtime dependency"}}
node_external(("External programs<br/>child processes"))

node_user -->|"enters commands"| node_msh
node_msh -->|"uses"| node_utils
node_msh -->|"parses command"| node_parser_wrapper
node_parser_wrapper -->|"invokes native parser"| node_parser_c
node_parser_c -->|"implements"| node_parser_header
node_msh -->|"built-in command"| node_builtin
node_msh -->|"external command"| node_executor
node_builtin -->|"uses"| node_utils
node_executor -->|"delegates launch"| node_fork_exec
node_fork_exec -->|"forks and execs"| node_external
node_parser_c -.->|"runs on"| node_posix
node_fork_exec -->|"uses process APIs"| node_posix

click node_msh "https://github.com/mahakagarwal7/os-shell/blob/main/msh.sh"
click node_utils "https://github.com/mahakagarwal7/os-shell/blob/main/lib/utils.sh"
click node_parser_wrapper "https://github.com/mahakagarwal7/os-shell/blob/main/lib/parser.sh"
click node_builtin "https://github.com/mahakagarwal7/os-shell/blob/main/lib/builtin.sh"
click node_executor "https://github.com/mahakagarwal7/os-shell/blob/main/lib/executor.sh"
click node_parser_header "https://github.com/mahakagarwal7/os-shell/blob/main/include/parser.h"
click node_parser_c "https://github.com/mahakagarwal7/os-shell/blob/main/c_src/parser.c"
click node_fork_exec "https://github.com/mahakagarwal7/os-shell/blob/main/c_src/fork_exec.c"

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_msh,node_utils,node_parser_wrapper,node_builtin,node_executor toneBlue
class node_parser_header,node_parser_c,node_fork_exec toneAmber
class node_user,node_posix,node_external toneNeutral
```

## Components

### Bash shell

- [Shell control loop](https://github.com/mahakagarwal7/os-shell/blob/main/msh.sh): Bash entry point · Reads input and routes commands. · `msh.sh`
- [Shared utilities](https://github.com/mahakagarwal7/os-shell/blob/main/lib/utils.sh): Bash library · `lib/utils.sh`
- [Parser wrapper](https://github.com/mahakagarwal7/os-shell/blob/main/lib/parser.sh): Bash library · `lib/parser.sh`
- [Built-in commands](https://github.com/mahakagarwal7/os-shell/blob/main/lib/builtin.sh): Bash dispatch · Runs stateful commands in the shell process. · `lib/builtin.sh`
- [External executor](https://github.com/mahakagarwal7/os-shell/blob/main/lib/executor.sh): Bash coordinator · `lib/executor.sh`

### Native process layer

- [Parser interface](https://github.com/mahakagarwal7/os-shell/blob/main/include/parser.h): C header · `include/parser.h`
- [Native parser](https://github.com/mahakagarwal7/os-shell/blob/main/c_src/parser.c): C implementation · `c_src/parser.c`
- [Fork/exec runtime](https://github.com/mahakagarwal7/os-shell/blob/main/c_src/fork_exec.c): C process launcher · Launches external commands in child processes. · `c_src/fork_exec.c`

### Other components

- **Shell user**: actor
- **Unix/POSIX runtime**: runtime dependency · Provides shell execution and process primitives.
- **External programs**: child processes

## Connections

- Shell user → Shell control loop: enters commands
- Shell control loop → Shared utilities: uses
- Shell control loop → Parser wrapper: parses command
- Parser wrapper → Native parser: invokes native parser
- Native parser → Parser interface: implements
- Shell control loop → Built-in commands: built-in command
- Shell control loop → External executor: external command
- Built-in commands → Shared utilities: uses
- External executor → Fork/exec runtime: delegates launch
- Fork/exec runtime → External programs: forks and execs
- Native parser → Unix/POSIX runtime: runs on
- Fork/exec runtime → Unix/POSIX runtime: uses process APIs