# gutslike/shell-in-go architecture

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

- Interactive diagram: https://gitdiagram.com/gutslike/shell-in-go
- Repository: https://github.com/gutslike/shell-in-go

## Overview

#### Purpose and Entry Point

This is a minimal, cross-platform interactive command-line shell implemented in Go. Its sole executable entry point is [`main.go`](main.go); module and Go-version dependencies are defined in [`go.mod`](go.mod).

#### Interactive REPL Loop

[`main.go`](main.go) owns the shell lifecycle: display a prompt, read a user command, interpret it, execute it, and repeat until `exit` terminates the process. There is no server, UI framework, or persistent application state.

#### Command Input and Dispatch

Input is treated as a command plus arguments and dispatched through a builtin-versus-external boundary in [`main.go`](main.go). The current command model is intentionally simple; quoted parsing, expansions, redirection, pipelines, and job control are planned but not present architectural stages yet.

#### Builtin Command Layer

[`main.go`](main.go) implements shell-native commands:
- `echo` writes supplied arguments.
- `exit` ends the REPL/process.
- `type` reports whether a command is builtin or resolves to an executable.

Builtins run inside the shell process, rather than being delegated to the operating system.

#### External Process Resolution and Execution

For non-builtin commands, [`main.go`](main.go) searches directories in the host `PATH` environment variable, then launches the resolved executable as a child process. On Windows, resolution additionally depends on `PATHEXT` executable extensions; Linux and macOS/Unix use normal executable paths.

#### Runtime and OS Boundary

The runtime is Go 1.24+ as declared/managed through [`go.mod`](go.mod). The principal external dependencies are the local terminal for standard input/output, the host environment (`PATH`, and Windows `PATHEXT`), and operating-system process execution facilities. No databases, network services, containers, or cloud infrastructure are indicated.

#### Evolution Boundary

The repository deliberately keeps all behavior in [`main.go`](main.go) while shell semantics are being learned incrementally. Future features—working-directory mutation, parsing quotes, redirection, pipes, expansion, history, completion, and job control—will require separating parsing, command resolution, execution, and interactive-state management into dedicated packages or files.

Main entry points: [`main.go`](https://github.com/gutslike/shell-in-go/blob/main/main.go) (Command dispatch), [`go.mod`](https://github.com/gutslike/shell-in-go/blob/main/go.mod) (go.mod)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Go Shell"]
  node_main["main.go<br/>REPL entry point<br/>[main.go]"]
  node_prompt["Prompt and input<br/>REPL stage<br/>[main.go]"]
  node_dispatch["Command dispatch<br/>REPL stage<br/>[main.go]"]
  node_builtins["Builtins<br/>shell-native commands<br/>[main.go]"]
  node_resolution["Executable resolution<br/>process lookup<br/>[main.go]"]
  node_execution["Child process execution<br/>process launcher<br/>[main.go]"]
  node_module["go.mod<br/>Go module definition<br/>[go.mod]"]
end

subgraph group_host["Host Runtime"]
  node_terminal["Local terminal<br/>stdin/stdout"]
  node_environment["Host environment<br/>PATH / PATHEXT"]
  node_os["Operating system<br/>process facilities"]
  node_go["Go runtime"]
end

node_go -->|"runs"| node_main
node_module -->|"declares version"| node_go
node_terminal -->|"command input"| node_prompt
node_main -->|"REPL loop"| node_prompt
node_prompt -->|"command line"| node_dispatch
node_dispatch -->|"builtin"| node_builtins
node_dispatch -->|"external command"| node_resolution
node_builtins -->|"output"| node_terminal
node_resolution -->|"reads"| node_environment
node_resolution -->|"resolved executable"| node_execution
node_execution -->|"creates child process"| node_os
node_execution -->|"inherits I/O"| node_terminal
node_builtins -.->|"exit terminates"| node_main

click node_main "https://github.com/gutslike/shell-in-go/blob/main/main.go"
click node_prompt "https://github.com/gutslike/shell-in-go/blob/main/main.go"
click node_dispatch "https://github.com/gutslike/shell-in-go/blob/main/main.go"
click node_builtins "https://github.com/gutslike/shell-in-go/blob/main/main.go"
click node_resolution "https://github.com/gutslike/shell-in-go/blob/main/main.go"
click node_execution "https://github.com/gutslike/shell-in-go/blob/main/main.go"
click node_module "https://github.com/gutslike/shell-in-go/blob/main/go.mod"

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_main,node_prompt,node_dispatch,node_builtins,node_resolution,node_execution,node_module toneBlue
class node_terminal,node_environment,node_os,node_go toneAmber
```

## Components

### Go Shell

- [main.go](https://github.com/gutslike/shell-in-go/blob/main/main.go): REPL entry point · Owns the complete interactive shell lifecycle. · `main.go`
- [Prompt and input](https://github.com/gutslike/shell-in-go/blob/main/main.go): REPL stage · Displays a prompt and reads one command line. · `main.go`
- [Command dispatch](https://github.com/gutslike/shell-in-go/blob/main/main.go): REPL stage · Splits command input and selects builtin or external handling. · `main.go`
- [Builtins](https://github.com/gutslike/shell-in-go/blob/main/main.go): shell-native commands · Implements echo, exit, and type in the shell process. · `main.go`
- [Executable resolution](https://github.com/gutslike/shell-in-go/blob/main/main.go): process lookup · Searches PATH; Windows also uses PATHEXT. · `main.go`
- [Child process execution](https://github.com/gutslike/shell-in-go/blob/main/main.go): process launcher · Launches resolved non-builtin commands. · `main.go`
- [go.mod](https://github.com/gutslike/shell-in-go/blob/main/go.mod): Go module definition · Declares Go 1.24+ module requirements. · `go.mod`

### Host Runtime

- **Local terminal**: stdin/stdout
- **Host environment**: PATH / PATHEXT
- **Operating system**: process facilities
- **Go runtime**: runtime

## Connections

- Go runtime → main.go: runs
- go.mod → Go runtime: declares version
- Local terminal → Prompt and input: command input
- main.go → Prompt and input: REPL loop
- Prompt and input → Command dispatch: command line
- Command dispatch → Builtins: builtin
- Command dispatch → Executable resolution: external command
- Builtins → Local terminal: output
- Executable resolution → Host environment: reads
- Executable resolution → Child process execution: resolved executable
- Child process execution → Operating system: creates child process
- Child process execution → Local terminal: inherits I/O
- Builtins → main.go: exit terminates