# benaliossama/0-shell architecture

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

- Interactive diagram: https://gitdiagram.com/benaliossama/0-shell
- Repository: https://github.com/benaliossama/0-shell

## Overview

##### Project type and purpose
- This is a command-line shell implementation in Rust.
- It consists of modules for parsing user input, executing commands (both built-in and external), and the top‐level “shell” binary that ties everything together.

##### File structure
- Top-level crates:
- parsing/       (lexing & parsing user input)
- executer/      (dispatching and running commands)
- shell/         (the interactive shell REPL)
- commands/      (definitions of built-in commands and sub-crates for external-like utilities)
- tools/ls       (an example standalone utility)
- bin/ls – another example of shipping a binary (similar to tools/ls).
- Cargo.toml at root – workspace manifest tying all sub‐crates together.

##### Key excerpts from the README
- Very minimal: “for now, make then make build.”

##### Main components
a. REPL (shell/) – reads user input, displays prompt, sends raw input downstream
b. Parser (parsing/) – lexes and parses the raw input into an AST or command structure
c. Executor (executer/) – takes the parsed structure and:
- dispatches to built-in commands (commands/src/builtin)
- forks and executes external binaries (tools/ls, commands/src/bin/ls, system PATH)
d. Built-in commands module (commands/src/builtin) – cd, clear, echo, exit, pwd, etc.
e. External commands sub-crates (commands/src/bin/ls, tools/ls, bin/ls) – example utilities published or vendored in the workspace
f. Operating System / File System – underlying environment for external command execution

##### Relationships & data flow
- REPL → Parser: raw text
- Parser → Executor: parsed AST/command struct
- Executor → Built-ins: direct function calls (in-process)
- Executor → External: spawn child processes via OS APIs
- Executor → REPL: return status code / stdout / stderr for display
- REPL → User: display prompt, command output

##### Architectural patterns & design principles
- Modular crate separation per concern (parsing, execution, commands, shell UI)
- Workspace structure for shared code and consistent builds
- Clear separation between built-in (in-process) and external (out-of-process) commands
- Single responsibility: each crate handles one layer of the shell pipeline

##### Relevant technologies, frameworks, libraries
- Rust & Cargo workspaces
- Standard library for I/O, process spawning
- Custom parser module in parsing/
- In-process command dispatch in executer/

- [ ] Each component clearly labeled (with crate path)
- [ ] Layer separation (UI layer, parsing layer, execution layer)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    User["User"]:::user
    ShellREPL["Shell REPL<br/>(shell/)"]:::repl

    %% Parsing Layer
    Parser["Parser<br/>(parsing/)"]:::inproc

    %% Execution Layer
    Executor["Executor<br/>(executer/)"]:::inproc

    %% Commands Crate
    subgraph "Commands Crate (commands/)"
        BuiltIns["Built-in Commands<br/>(commands/src/builtin)"]:::inproc
        VendoredLS["vendored ls<br/>(commands/src/bin/ls)"]:::external
    end

    %% External Utilities
    ToolsLS["tools/ls"]:::external
    BinLS["bin/ls"]:::external

    %% Operating System
    OSFS["OS / File System"]:::os

    %% Data Flows
    User -->|"stdin/stdout"| ShellREPL
    ShellREPL -->|"Raw input"| Parser
    Parser -->|"Parsed AST"| Executor
    Executor -->|"Function call"| BuiltIns
    Executor -->|"spawn child process"| VendoredLS
    Executor -->|"spawn child process"| ToolsLS
    Executor -->|"spawn child process"| BinLS
    VendoredLS -->|"uses OS"| OSFS
    ToolsLS -->|"uses OS"| OSFS
    BinLS -->|"uses OS"| OSFS
    Executor -->|"Exit code & output"| ShellREPL
    ShellREPL -->|"stdout/stderr"| User

    %% Click Events
    click ShellREPL "https://github.com/benaliossama/0-shell/blob/main/shell/src/main.rs"
    click Parser "https://github.com/benaliossama/0-shell/blob/main/parsing/src/main.rs"
    click Executor "https://github.com/benaliossama/0-shell/blob/main/executer/src/lib.rs"
    click BuiltIns "https://github.com/benaliossama/0-shell/blob/main/commands/src/builtin/mod.rs"
    click VendoredLS "https://github.com/benaliossama/0-shell/blob/main/commands/src/bin/ls/src/main.rs"
    click ToolsLS "https://github.com/benaliossama/0-shell/blob/main/tools/ls/src/main.rs"
    click BinLS "https://github.com/benaliossama/0-shell/tree/main/bin/ls"
    click Workspace "https://github.com/benaliossama/0-shell/blob/main/Cargo.toml"

    %% Styles
    classDef repl fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef inproc fill:#aaddff,stroke:#333,stroke-width:1px
    classDef external fill:#ffbb88,stroke:#333,stroke-width:1px
    classDef os fill:#dddddd,stroke:#333,stroke-width:1px
    classDef user fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
