# satvik-pachipulusu/shellforgex architecture

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

- Interactive diagram: https://gitdiagram.com/satvik-pachipulusu/shellforgex
- Repository: https://github.com/satvik-pachipulusu/shellforgex

## Overview

ShellForge X is a C/POSIX interactive shell. Its main workflow reads commands in a REPL, records and dispatches them to built-ins or command, pipeline, and redirection execution. It also exposes job, memory, synchronization, dashboard, and AI features. The README describes telemetry and LLM integration as educational capabilities, with some still upcoming. The graph follows the visible shell dispatch; several implementation details and the Python helper’s wiring are not established by the excerpts.

Main entry points: [`src/shell.c`](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/shell.c) (Interactive REPL), [`src/main.c`](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/main.c) (Program entry), [`src/pipeline.c`](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/pipeline.c) (Pipeline execution), [`src/ai.c`](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/ai.c) (AI assistance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Shell interface"]
  node_entry["Program entry<br/>[main.c]"]
  node_repl["Interactive REPL<br/>[shell.c]"]
  node_signals["Signal setup<br/>[signals.c]"]
  node_history["Command history<br/>[history.c]"]
end

subgraph group_execution["Command execution"]
  node_builtins["Built-in commands<br/>[builtin.c]"]
  node_process["Command execution<br/>[process.c]"]
  node_pipeline["Pipeline execution<br/>[pipeline.c]"]
  node_parser["Command parser<br/>[parser.c]"]
  node_redirection["I/O redirection<br/>[redirection.c]"]
end

subgraph group_state["Jobs and OS concepts"]
  node_jobs["Job control<br/>[jobs.c]"]
  node_memstat["Memory statistics<br/>[memstat.c]"]
  node_sync["Deadlock demo<br/>[sync_demo.c]"]
end

subgraph group_education["Educational features"]
  node_dashboard["OS dashboard<br/>[dashboard.c]"]
  node_ai["AI assistance<br/>[ai.c]"]
  node_aihelper["AI helper<br/>[ai_helper.py]"]
end

node_user(("Shell user"))

node_user -->|"starts shell"| node_entry
node_entry -->|"sets handlers"| node_signals
node_entry -->|"starts REPL"| node_repl
node_user -->|"enters commands"| node_repl
node_repl -->|"records commands"| node_history
node_repl -->|"dispatches built-ins"| node_builtins
node_repl -->|"dispatches commands"| node_process
node_repl -->|"dispatches pipelines"| node_pipeline
node_repl -->|"dispatches redirection"| node_redirection
node_pipeline -->|"parses commands"| node_parser
node_repl -->|"shows and reaps"| node_jobs
node_repl -->|"dispatches memstat"| node_memstat
node_repl -->|"dispatches deadlock"| node_sync
node_repl -->|"dispatches dashboard"| node_dashboard
node_repl -->|"dispatches AI requests"| node_ai
node_ai -.-> node_aihelper

click node_entry "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/main.c"
click node_repl "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/shell.c"
click node_signals "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/signals.c"
click node_history "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/history.c"
click node_builtins "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/builtin.c"
click node_process "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/process.c"
click node_pipeline "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/pipeline.c"
click node_parser "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/parser.c"
click node_redirection "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/redirection.c"
click node_jobs "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/jobs.c"
click node_memstat "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/memstat.c"
click node_sync "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/sync_demo.c"
click node_dashboard "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/dashboard.c"
click node_ai "https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/ai.c"
click node_aihelper "https://github.com/satvik-pachipulusu/shellforgex/blob/main/ai_helper.py"

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_entry,node_repl,node_signals,node_history,node_user toneBlue
class node_builtins,node_process,node_pipeline,node_parser,node_redirection toneAmber
class node_jobs,node_memstat,node_sync toneMint
class node_dashboard,node_ai,node_aihelper toneRose
```

## Components

### Shell interface

- [Program entry](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/main.c): `src/main.c`
- [Interactive REPL](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/shell.c): `src/shell.c`
- [Signal setup](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/signals.c): `src/signals.c`
- [Command history](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/history.c): `src/history.c`

### Command execution

- [Built-in commands](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/builtin.c): `src/builtin.c`
- [Command execution](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/process.c): `src/process.c`
- [Pipeline execution](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/pipeline.c): `src/pipeline.c`
- [Command parser](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/parser.c): `src/parser.c`
- [I/O redirection](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/redirection.c): `src/redirection.c`

### Jobs and OS concepts

- [Job control](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/jobs.c): `src/jobs.c`
- [Memory statistics](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/memstat.c): `src/memstat.c`
- [Deadlock demo](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/sync_demo.c): `src/sync_demo.c`

### Educational features

- [OS dashboard](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/dashboard.c): `src/dashboard.c`
- [AI assistance](https://github.com/satvik-pachipulusu/shellforgex/blob/main/src/ai.c): `src/ai.c`
- [AI helper](https://github.com/satvik-pachipulusu/shellforgex/blob/main/ai_helper.py): `ai_helper.py`

### Other components

- **Shell user**

## Connections

- Shell user → Program entry: starts shell (evidence: `README.md`)
- Program entry → Signal setup: sets handlers (evidence: `src/main.c`)
- Program entry → Interactive REPL: starts REPL (evidence: `src/main.c`)
- Shell user → Interactive REPL: enters commands (evidence: `README.md`)
- Interactive REPL → Command history: records commands (evidence: `src/shell.c`)
- Interactive REPL → Built-in commands: dispatches built-ins (evidence: `src/shell.c`)
- Interactive REPL → Command execution: dispatches commands (evidence: `src/shell.c`)
- Interactive REPL → Pipeline execution: dispatches pipelines (evidence: `src/shell.c`)
- Interactive REPL → I/O redirection: dispatches redirection (evidence: `src/shell.c`)
- Pipeline execution → Command parser: parses commands (evidence: `src/pipeline.c`)
- Interactive REPL → Job control: shows and reaps (evidence: `src/shell.c`)
- Interactive REPL → Memory statistics: dispatches memstat (evidence: `src/shell.c`)
- Interactive REPL → Deadlock demo: dispatches deadlock (evidence: `src/shell.c`)
- Interactive REPL → OS dashboard: dispatches dashboard (evidence: `src/shell.c`)
- Interactive REPL → AI assistance: dispatches AI requests (evidence: `src/shell.c`)
- AI assistance → AI helper