# cadenfinley/cjsh architecture

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

- Interactive diagram: https://gitdiagram.com/cadenfinley/cjsh
- Repository: https://github.com/cadenfinley/cjsh

## Overview

cjsh is a POSIX-first scripting shell with a richer interactive terminal experience. A user enters commands at the interactive prompt or supplies a script; the shell parses and interprets shell syntax, expands values and patterns, then dispatches builtins or external commands and tracks execution status. Interactive editing, completions, highlighting, prompt styling, keybindings, and history are major documented capabilities. The source index supports several execution dependencies; other links are left dashed where implementation excerpts were not provided.

Main entry points: [`cjsh-isocline/src/edit/editline.c`](https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/edit/editline.c) (Line editor), [`cjsh-core/src/interpreter/interpreter.cpp`](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/interpreter/interpreter.cpp) (Interpreter), [`cjsh-core/src/exec/exec.cpp`](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/exec/exec.cpp) (Command execution), [`cjsh-core/src/core/shell.cpp`](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/shell.cpp) (Shell lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Shell Runtime"]
  node_shell["Shell lifecycle<br/>[shell.cpp]"]
  node_loop["Interactive loop<br/>[main_loop.cpp]"]
  node_dispatch["Command execution<br/>[exec.cpp]"]
  node_builtins["Builtin commands"]
  node_jobs["Job control<br/>[job_control.cpp]"]
  node_signals["Signal handling<br/>[signal_handler.cpp]"]
end

subgraph group_language["Shell Language"]
  node_parser["Command parser<br/>[parser.cpp]"]
  node_interpreter["Interpreter<br/>[interpreter.cpp]"]
  node_expansion["Word expansion"]
  node_variables["Variable manager"]
  node_validation["Command validation<br/>[validation.cpp]"]
end

subgraph group_interactive["Interactive Experience"]
  node_editor["Line editor<br/>[editline.c]"]
  node_completion["Completions"]
  node_highlight["Syntax highlighting"]
  node_prompt["Prompt styling<br/>[prompt.cpp]"]
  node_history["History search<br/>[history.c]"]
  node_isohistory["Editor history<br/>[history.c]"]
end

subgraph group_terminal["Terminal Services"]
  node_terminalio["Terminal I/O<br/>[tty.c]"]
  node_termrender["Terminal rendering<br/>[term.c]"]
end

node_user(("Shell user"))

node_user -.->|"enters commands"| node_loop
node_loop -.->|"runs shell"| node_shell
node_shell -->|"uses parser"| node_parser
node_shell -->|"uses signals"| node_signals
node_parser -.->|"passes syntax"| node_interpreter
node_interpreter -.->|"expands words"| node_expansion
node_interpreter -.->|"accesses variables"| node_variables
node_interpreter -.->|"validates commands"| node_validation
node_dispatch -->|"invokes interpreter"| node_interpreter
node_dispatch -->|"dispatches builtins"| node_builtins
node_dispatch -->|"uses job control"| node_jobs
node_dispatch -->|"uses shell state"| node_shell
node_loop -.->|"reads input"| node_editor
node_editor -.->|"requests candidates"| node_completion
node_editor -.->|"highlights input"| node_highlight
node_editor -.->|"displays prompt"| node_prompt
node_editor -.->|"uses history"| node_isohistory
node_editor -->|"reads keystrokes"| node_terminalio
node_editor -->|"renders line"| node_termrender
node_terminalio -->|"supports terminal"| node_termrender

click node_shell "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/shell.cpp"
click node_loop "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/main_loop.cpp"
click node_parser "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/parser/parser.cpp"
click node_interpreter "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/interpreter/interpreter.cpp"
click node_expansion "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/parser/expansion_engine.cpp"
click node_variables "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/interpreter/variable_manager.cpp"
click node_validation "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/validation/validation.cpp"
click node_dispatch "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/exec/exec.cpp"
click node_builtins "https://github.com/cadenfinley/cjsh/tree/master/cjsh-core/src/builtin"
click node_jobs "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/job_control.cpp"
click node_signals "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/signal_handler.cpp"
click node_editor "https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/edit/editline.c"
click node_completion "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/completion/cjsh_completions.cpp"
click node_highlight "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/highlighter/cjsh_syntax_highlighter.cpp"
click node_prompt "https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/prompt.cpp"
click node_history "https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/edit/history.c"
click node_terminalio "https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/terminal/tty.c"
click node_termrender "https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/terminal/term.c"
click node_isohistory "https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/edit/history.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_shell,node_loop,node_dispatch,node_builtins,node_jobs,node_signals,node_user toneBlue
class node_parser,node_interpreter,node_expansion,node_variables,node_validation toneAmber
class node_editor,node_completion,node_highlight,node_prompt,node_history,node_isohistory toneMint
class node_terminalio,node_termrender toneRose
```

## Components

### Shell Runtime

- [Shell lifecycle](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/shell.cpp): `cjsh-core/src/core/shell.cpp`
- [Interactive loop](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/main_loop.cpp): `cjsh-core/src/core/main_loop.cpp`
- [Command execution](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/exec/exec.cpp): `cjsh-core/src/exec/exec.cpp`
- [Builtin commands](https://github.com/cadenfinley/cjsh/tree/master/cjsh-core/src/builtin): `cjsh-core/src/builtin`
- [Job control](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/job_control.cpp): `cjsh-core/src/core/job_control.cpp`
- [Signal handling](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/signal_handler.cpp): `cjsh-core/src/core/signal_handler.cpp`

### Shell Language

- [Command parser](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/parser/parser.cpp): `cjsh-core/src/parser/parser.cpp`
- [Interpreter](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/interpreter/interpreter.cpp): `cjsh-core/src/interpreter/interpreter.cpp`
- [Word expansion](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/parser/expansion_engine.cpp): `cjsh-core/src/parser/expansion_engine.cpp`
- [Variable manager](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/interpreter/variable_manager.cpp): `cjsh-core/src/interpreter/variable_manager.cpp`
- [Command validation](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/validation/validation.cpp): `cjsh-core/src/validation/validation.cpp`

### Interactive Experience

- [Line editor](https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/edit/editline.c): `cjsh-isocline/src/edit/editline.c`
- [Completions](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/completion/cjsh_completions.cpp): `cjsh-core/src/completion/cjsh_completions.cpp`
- [Syntax highlighting](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/highlighter/cjsh_syntax_highlighter.cpp): `cjsh-core/src/highlighter/cjsh_syntax_highlighter.cpp`
- [Prompt styling](https://github.com/cadenfinley/cjsh/blob/master/cjsh-core/src/core/prompt.cpp): `cjsh-core/src/core/prompt.cpp`
- [History search](https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/edit/history.c): `cjsh-isocline/src/edit/history.c`
- [Editor history](https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/edit/history.c): `cjsh-isocline/src/edit/history.c`

### Terminal Services

- [Terminal I/O](https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/terminal/tty.c): `cjsh-isocline/src/terminal/tty.c`
- [Terminal rendering](https://github.com/cadenfinley/cjsh/blob/master/cjsh-isocline/src/terminal/term.c): `cjsh-isocline/src/terminal/term.c`

### Other components

- **Shell user**

## Connections

- Shell user → Interactive loop: enters commands
- Interactive loop → Shell lifecycle: runs shell
- Shell lifecycle → Command parser: uses parser
- Shell lifecycle → Signal handling: uses signals
- Command parser → Interpreter: passes syntax
- Interpreter → Word expansion: expands words
- Interpreter → Variable manager: accesses variables
- Interpreter → Command validation: validates commands
- Command execution → Interpreter: invokes interpreter (evidence: `cjsh-core/src/exec/exec.cpp`)
- Command execution → Builtin commands: dispatches builtins (evidence: `cjsh-core/src/exec/exec.cpp`)
- Command execution → Job control: uses job control (evidence: `cjsh-core/src/exec/exec.cpp`)
- Command execution → Shell lifecycle: uses shell state (evidence: `cjsh-core/src/exec/exec.cpp`)
- Interactive loop → Line editor: reads input
- Line editor → Completions: requests candidates
- Line editor → Syntax highlighting: highlights input
- Line editor → Prompt styling: displays prompt
- Line editor → Editor history: uses history
- Line editor → Terminal I/O: reads keystrokes (evidence: `cjsh-isocline/src/edit/editline.c`)
- Line editor → Terminal rendering: renders line (evidence: `cjsh-isocline/src/edit/editline.c`)
- Terminal I/O → Terminal rendering: supports terminal (evidence: `cjsh-isocline/src/terminal/term.c`)