# raslan07/codecrafters-shell-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/raslan07/codecrafters-shell-cpp
- Repository: https://github.com/raslan07/codecrafters-shell-cpp

## Overview

1. **Repository purpose**
   - This is a C++ starter repository for a CodeCrafters “Build Your Own Shell” challenge.
   - The intended product is a POSIX-like shell that reads commands, parses them, runs builtins, and launches external programs.

2. **Core application boundary**
   - The only application source file shown is `src/main.cpp`.
   - That file is the primary runtime entry point and is where the shell implementation lives.
   - For an architecture diagram, treat `main.cpp` as the center of the system: input loop, command handling, and process execution all originate there.

3. **Build system**
   - The project uses **CMake** (`CMakeLists.txt`) as the build orchestrator.
   - CMake is the main boundary between source code and the compiled executable.
   - This is a single-binary style project rather than a multi-service system.

4. **Dependency management**
   - The repo includes `vcpkg.json` and `vcpkg-configuration.json`, so external C++ dependencies are managed through **vcpkg**.
   - In architecture terms, this means third-party libraries are resolved at build time, not through a runtime package manager or service dependency.

5. **Execution wrapper**
   - `your_program.sh` is the local run script called by the challenge tooling.
   - It serves as the stable command entrypoint for running the compiled shell during development and evaluation.
   - The actual executable behavior still comes from the C++ program in `src/main.cpp`.

6. **Codecrafters integration**
   - The `.codecrafters/compile.sh` and `.codecrafters/run.sh` scripts are infrastructure adapters used by the CodeCrafters platform.
   - They wrap the local build/run process so the platform can compile and execute the solution consistently.
   - These scripts are not application logic; they are part of the test harness boundary.

7. **Runtime interaction model**
   - The shell is expected to be interactive: it reads user input from standard input, emits prompts/output to standard output, and may invoke child processes.
   - Important data flow for the eventual implementation: terminal input → parsing/dispatch → builtin handling or external process execution → terminal output.

8. **Shell-specific functional subsystems**
   - Even though the current repo is mostly scaffolding, the target architecture implied by the challenge includes:
     - command parser
     - builtin command dispatcher
     - external command launcher
     - REPL loop
   - These are logical modules that will likely be implemented inside `src/main.cpp` or split into additional source files later.

9. **What is not present**
   - There is no evidence of a network layer, database, message queue, or web frontend.
   - This is a local CLI application with build/test automation around it, not a distributed system.

10. **Practical diagram framing**
   - A clear diagram would show:
     - developer / CodeCrafters test runner at the top
     - build scripts and CMake as the build path
     - the compiled shell executable in the middle
     - stdin/stdout/stderr and spawned child processes as the runtime interfaces
   - The repo’s main architectural distinction is between **implementation code** (`src/main.cpp`) and **evaluation/tooling** (`.codecrafters/*`, `your_program.sh`, CMake/vcpkg files).

Main entry points: [`.codecrafters/compile.sh`](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/.codecrafters/compile.sh) (Compile script), [`.codecrafters/run.sh`](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/.codecrafters/run.sh) (Run script), [`your_program.sh`](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/your_program.sh) (Program script), [`CMakeLists.txt`](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/CMakeLists.txt) (CMake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tooling["Tooling"]
  node_developer(("Developer<br/>actor"))
  node_codecrafters_compile["Compile script<br/>adapter<br/>[compile.sh]"]
  node_codecrafters_run["Run script<br/>adapter<br/>[run.sh]"]
  node_your_program["Program script<br/>entry script<br/>[your_program.sh]"]
end

subgraph group_build["Build"]
  node_cmake["CMake<br/>build config<br/>[CMakeLists.txt]"]
  node_vcpkg_manifest["vcpkg manifest<br/>deps manifest<br/>[vcpkg.json]"]
  node_vcpkg_config["vcpkg config<br/>deps config"]
end

subgraph group_runtime["Runtime"]
  node_shell_binary["Shell binary<br/>compiled executable"]
  node_main_cpp["Main shell<br/>cpp entrypoint<br/>[main.cpp]"]
  node_repl_loop(("REPL loop<br/>interactive loop"))
  node_terminal_io(("Terminal I/O<br/>stdio boundary"))
  node_parser{{"Command parser"}}
  node_builtins["Builtin dispatcher<br/>builtin router"]
  node_launcher["Process launcher<br/>exec launcher"]
  node_child_proc(("Child process<br/>spawned process"))
end

node_developer -->|"builds"| node_codecrafters_compile
node_developer -->|"runs"| node_codecrafters_run
node_developer -->|"executes"| node_your_program
node_codecrafters_compile -->|"invokes"| node_cmake
node_codecrafters_compile -->|"resolves deps"| node_vcpkg_manifest
node_codecrafters_compile -->|"configures deps"| node_vcpkg_config
node_cmake -->|"produces"| node_shell_binary
node_vcpkg_manifest -->|"links deps"| node_shell_binary
node_vcpkg_config -->|"links deps"| node_shell_binary
node_your_program -->|"launches"| node_shell_binary
node_codecrafters_run -->|"launches"| node_shell_binary
node_shell_binary -->|"contains"| node_main_cpp
node_main_cpp -->|"drives"| node_repl_loop
node_repl_loop -->|"reads/writes"| node_terminal_io
node_repl_loop -->|"parses"| node_parser
node_parser -->|"dispatches"| node_builtins
node_parser -->|"dispatches"| node_launcher
node_builtins -->|"outputs"| node_terminal_io
node_launcher -->|"spawns"| node_child_proc
node_child_proc -->|"streams"| node_terminal_io

click node_codecrafters_compile "https://github.com/raslan07/codecrafters-shell-cpp/blob/main/.codecrafters/compile.sh"
click node_codecrafters_run "https://github.com/raslan07/codecrafters-shell-cpp/blob/main/.codecrafters/run.sh"
click node_your_program "https://github.com/raslan07/codecrafters-shell-cpp/blob/main/your_program.sh"
click node_cmake "https://github.com/raslan07/codecrafters-shell-cpp/blob/main/CMakeLists.txt"
click node_vcpkg_manifest "https://github.com/raslan07/codecrafters-shell-cpp/blob/main/vcpkg.json"
click node_vcpkg_config "https://github.com/raslan07/codecrafters-shell-cpp/blob/main/vcpkg-configuration.json"
click node_main_cpp "https://github.com/raslan07/codecrafters-shell-cpp/blob/main/src/main.cpp"

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_developer,node_codecrafters_compile,node_codecrafters_run,node_your_program toneBlue
class node_cmake,node_vcpkg_manifest,node_vcpkg_config toneAmber
class node_shell_binary,node_main_cpp,node_repl_loop,node_terminal_io,node_parser,node_builtins,node_launcher,node_child_proc toneMint
```

## Components

### Tooling

Challenge and local execution adapters around the shell implementation

- **Developer**: actor · Local developer or CodeCrafters test runner triggering the repo workflow
- [Compile script](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/.codecrafters/compile.sh): adapter · CodeCrafters wrapper for building the solution · `.codecrafters/compile.sh`
- [Run script](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/.codecrafters/run.sh): adapter · CodeCrafters wrapper for running the solution · `.codecrafters/run.sh`
- [Program script](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/your_program.sh): entry script · Stable local entrypoint used to launch the compiled shell · `your_program.sh`

### Build

CMake and vcpkg boundary that produces the executable

- [CMake](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/CMakeLists.txt): build config · Primary build orchestrator for the single-binary C++ project · `CMakeLists.txt`
- [vcpkg manifest](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/vcpkg.json): deps manifest · Declares third-party C++ dependencies · `vcpkg.json`
- [vcpkg config](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/vcpkg-configuration.json): deps config · Configures vcpkg resolution for the build · `vcpkg-configuration.json`

### Runtime

Interactive shell loop and command execution flow

- **Shell binary**: compiled executable · The built command-line program produced from the C++ source
- [Main shell](https://github.com/raslan07/codecrafters-shell-cpp/blob/main/src/main.cpp): cpp entrypoint · Primary application code and runtime center of the shell · `src/main.cpp`
- **REPL loop**: interactive loop · Reads commands and drives the shell session
- **Terminal I/O**: stdio boundary · Standard input, output, and error used by the shell
- **Command parser**: parser · Turns raw input into executable command structure
- **Builtin dispatcher**: builtin router · Handles shell-native commands without spawning a child process
- **Process launcher**: exec launcher · Resolves and starts external programs
- **Child process**: spawned process · External command executed by the shell

## Connections

- Developer → Compile script: builds · The platform or developer invokes the compilation wrapper
- Developer → Run script: runs · The platform or developer invokes the runtime wrapper
- Developer → Program script: executes · Local workflow entrypoint for the compiled shell
- Compile script → CMake: invokes · Compile wrapper delegates to the CMake build
- Compile script → vcpkg manifest: resolves deps · Build uses the dependency manifest during compilation
- Compile script → vcpkg config: configures deps · Build uses vcpkg configuration for dependency resolution
- CMake → Shell binary: produces · CMake compiles the executable artifact
- vcpkg manifest → Shell binary: links deps · Third-party libraries are made available at build time
- vcpkg config → Shell binary: links deps · vcpkg configuration influences dependency resolution
- Program script → Shell binary: launches · Run script starts the compiled executable
- Run script → Shell binary: launches · CodeCrafters runtime wrapper starts the program
- Shell binary → Main shell: contains · The binary is built from the shell implementation
- Main shell → REPL loop: drives · Main application logic centers on the interactive loop
- REPL loop → Terminal I/O: reads/writes · Loop consumes stdin and emits prompts and results
- REPL loop → Command parser: parses · Each user command is parsed before dispatch
- Command parser → Builtin dispatcher: dispatches · Parsed commands may be handled by builtins
- Command parser → Process launcher: dispatches · Non-builtin commands are sent to external execution
- Builtin dispatcher → Terminal I/O: outputs · Builtins write results back to the terminal
- Process launcher → Child process: spawns · External commands execute in a child process
- Child process → Terminal I/O: streams · Child process uses the shell's standard streams