# gayathri-samudrala/shellforge90126 architecture

> Architecture diagram of the GitHub repository gayathri-samudrala/shellforge90126, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gayathri-samudrala/shellforge90126
- Repository: https://github.com/gayathri-samudrala/shellforge90126

## Overview

Shellforge is a Unix-style interactive shell. Its main workflow reads a command line, tokenizes and parses it into a pipeline, expands variables, then executes commands with built-ins, custom commands, or external programs. Execution also supports redirection, pipelines, background jobs, and job tracking; history is a separate shell capability. The graph follows the sampled entry point and executor excerpts plus the source index. Job-control code is included, but its wiring to execution is not established by the available excerpts.

Main entry points: [`src/main.c`](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/main.c) (Shell loop), [`src/executor.c`](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/executor.c) (Pipeline executor), [`src/lexer.c`](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/lexer.c) (Lexer), [`src/parser.c`](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/parser.c) (Pipeline parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Shell interaction"]
  node_main["Shell loop<br/>[main.c]"]
  node_history["History<br/>[history.c]"]
end

subgraph group_command["Command processing"]
  node_lexer["Lexer<br/>[lexer.c]"]
  node_tokens["Token model<br/>[token.c]"]
  node_parser["Pipeline parser<br/>[parser.c]"]
  node_expansion["Variable expansion<br/>[expand.c]"]
end

subgraph group_runtime["Command runtime"]
  node_executor["Pipeline executor<br/>[executor.c]"]
  node_builtins["Built-in commands<br/>[builtin.c]"]
  node_custom["Custom commands<br/>[custom_commands.c]"]
end

subgraph group_state["Shell state"]
  node_jobs[("Job registry<br/>[jobs.c]")]
  node_jobcontrol["Terminal job control<br/>[job_control.c]"]
end

node_user(("Shell user"))
node_programs["External programs"]
node_files[("Command files")]
node_processes["OS processes"]

node_user -->|"enters commands"| node_main
node_main -->|"tokenizes line"| node_lexer
node_main -->|"parses tokens"| node_parser
node_main -->|"expands variables"| node_expansion
node_main -->|"executes pipeline"| node_executor
node_main -->|"records and prints"| node_history
node_lexer -->|"creates tokens"| node_tokens
node_parser -->|"reads tokens"| node_tokens
node_executor -->|"dispatches built-ins"| node_builtins
node_executor -->|"dispatches custom"| node_custom
node_executor -->|"executes programs"| node_programs
node_executor -->|"redirects streams"| node_files
node_executor -->|"forks and waits"| node_processes
node_executor -->|"registers background jobs"| node_jobs
node_main -->|"initializes tracking"| node_jobs
node_main -.->|"job-control wiring unclear"| node_jobcontrol

click node_main "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/main.c"
click node_history "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/history.c"
click node_lexer "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/lexer.c"
click node_tokens "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/token.c"
click node_parser "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/parser.c"
click node_expansion "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/expand.c"
click node_executor "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/executor.c"
click node_builtins "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/builtin.c"
click node_custom "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/custom_commands.c"
click node_jobs "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/jobs.c"
click node_jobcontrol "https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/job_control.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_main,node_history,node_user toneBlue
class node_lexer,node_tokens,node_parser,node_expansion,node_files toneAmber
class node_executor,node_builtins,node_custom toneMint
class node_jobs,node_jobcontrol toneRose
class node_programs,node_processes toneIndigo
```

## Components

### Shell interaction

- [Shell loop](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/main.c): `src/main.c`
- [History](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/history.c): `src/history.c`

### Command processing

- [Lexer](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/lexer.c): `src/lexer.c`
- [Token model](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/token.c): `src/token.c`
- [Pipeline parser](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/parser.c): `src/parser.c`
- [Variable expansion](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/expand.c): `src/expand.c`

### Command runtime

- [Pipeline executor](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/executor.c): `src/executor.c`
- [Built-in commands](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/builtin.c): `src/builtin.c`
- [Custom commands](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/custom_commands.c): `src/custom_commands.c`

### Shell state

- [Job registry](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/jobs.c): `src/jobs.c`
- [Terminal job control](https://github.com/gayathri-samudrala/shellforge90126/blob/main/src/job_control.c): `src/job_control.c`

### Other components

- **Shell user**
- **External programs**
- **Command files**
- **OS processes**

## Connections

- Shell user → Shell loop: enters commands (evidence: `src/main.c`)
- Shell loop → Lexer: tokenizes line (evidence: `src/main.c`)
- Shell loop → Pipeline parser: parses tokens (evidence: `src/main.c`)
- Shell loop → Variable expansion: expands variables (evidence: `src/main.c`)
- Shell loop → Pipeline executor: executes pipeline (evidence: `src/main.c`)
- Shell loop → History: records and prints (evidence: `src/main.c`)
- Lexer → Token model: creates tokens
- Pipeline parser → Token model: reads tokens
- Pipeline executor → Built-in commands: dispatches built-ins (evidence: `src/executor.c`)
- Pipeline executor → Custom commands: dispatches custom (evidence: `src/executor.c`)
- Pipeline executor → External programs: executes programs (evidence: `src/executor.c`)
- Pipeline executor → Command files: redirects streams (evidence: `src/executor.c`)
- Pipeline executor → OS processes: forks and waits (evidence: `src/executor.c`)
- Pipeline executor → Job registry: registers background jobs (evidence: `src/executor.c`)
- Shell loop → Job registry: initializes tracking (evidence: `src/main.c`)
- Shell loop → Terminal job control: job-control wiring unclear