# mohamed-irban8738/punas-power-shell-pps architecture

> Architecture diagram of the GitHub repository mohamed-irban8738/punas-power-shell-pps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohamed-irban8738/punas-power-shell-pps
- Repository: https://github.com/mohamed-irban8738/punas-power-shell-pps

## Overview

Punas Power Shell is an educational command-line shell whose commands operate on an isolated, in-memory virtual filesystem. The main workflow is user input → parsing → command dispatch → shell handlers → filesystem operations → virtual filesystem state, with command history and logging recorded during the loop. The README also describes configuration and a broader command set, including extra commands. Edges reflect the shown excerpts or README; some command-registration wiring is not visible in the sampled shell excerpt, so it is not asserted.

Main entry points: [`src/shell.py`](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/shell.py) (Shell Engine), [`src/extra_commands.py`](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/extra_commands.py) (Extra Commands), [`src/filesystem.py`](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/filesystem.py) (File Manager), [`main.py`](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/main.py) (Application Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Shell Runtime"]
  node_entry["Application Entry<br/>[main.py]"]
  node_shell["Shell Engine<br/>[shell.py]"]
  node_parser["Command Parser<br/>[parser.py]"]
  node_dispatcher["Command Dispatcher<br/>[commands.py]"]
end

subgraph group_commands["Command Features"]
  node_handlers["Core Handlers<br/>[shell.py]"]
  node_extra["Extra Commands<br/>[extra_commands.py]"]
end

subgraph group_filesystem["Virtual Filesystem"]
  node_filemanager["File Manager<br/>[filesystem.py]"]
  node_vfs[("Virtual Filesystem<br/>[virtual_fs.py]")]
end

subgraph group_state["Session State"]
  node_history["Command History<br/>[history.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_configfile["Config File<br/>[config.json]"]
  node_logger["Activity Logger<br/>[logger.py]"]
  node_logfile["Log File"]
end

node_user(("Shell User"))

node_user -->|"starts shell"| node_entry
node_entry -->|"starts"| node_shell
node_user -->|"enters commands"| node_shell
node_shell -->|"parses input"| node_parser
node_shell -->|"dispatches commands"| node_dispatcher
node_shell -->|"runs file operations"| node_filemanager
node_shell -->|"records commands"| node_history
node_shell -->|"logs commands"| node_logger
node_shell -->|"loads settings"| node_config
node_filemanager -->|"delegates operations"| node_vfs
node_extra -->|"reads virtual files"| node_filemanager
node_extra -->|"traverses virtual paths"| node_vfs
node_extra -->|"registers handlers"| node_dispatcher
node_config -->|"loads and saves"| node_configfile
node_logger -->|"writes entries"| node_logfile
node_shell -.->|"registers extra commands"| node_extra

click node_entry "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/main.py"
click node_shell "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/shell.py"
click node_parser "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/parser.py"
click node_dispatcher "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/commands.py"
click node_handlers "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/shell.py"
click node_extra "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/extra_commands.py"
click node_filemanager "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/filesystem.py"
click node_vfs "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/virtual_fs.py"
click node_history "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/history.py"
click node_config "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/config.py"
click node_configfile "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/config.json"
click node_logger "https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/logger.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_shell,node_parser,node_dispatcher,node_user toneBlue
class node_handlers,node_extra toneAmber
class node_filemanager,node_vfs toneMint
class node_history,node_config,node_configfile,node_logger,node_logfile toneRose
```

## Components

### Shell Runtime

- [Application Entry](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/main.py): `main.py`
- [Shell Engine](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/shell.py): `src/shell.py`
- [Command Parser](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/parser.py): `src/parser.py`
- [Command Dispatcher](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/commands.py): `src/commands.py`

### Command Features

- [Core Handlers](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/shell.py): `src/shell.py`
- [Extra Commands](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/extra_commands.py): `src/extra_commands.py`

### Virtual Filesystem

- [File Manager](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/filesystem.py): `src/filesystem.py`
- [Virtual Filesystem](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/virtual_fs.py): `src/virtual_fs.py`

### Session State

- [Command History](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/history.py): `src/history.py`
- [Configuration](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/config.py): `src/config.py`
- [Config File](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/config.json): `config.json`
- [Activity Logger](https://github.com/mohamed-irban8738/punas-power-shell-pps/blob/main/src/logger.py): `src/logger.py`
- **Log File**

### Other components

- **Shell User**

## Connections

- Shell User → Application Entry: starts shell (evidence: `README.md`)
- Application Entry → Shell Engine: starts (evidence: `main.py`)
- Shell User → Shell Engine: enters commands (evidence: `README.md`)
- Shell Engine → Command Parser: parses input (evidence: `src/shell.py`)
- Shell Engine → Command Dispatcher: dispatches commands (evidence: `src/shell.py`)
- Shell Engine → File Manager: runs file operations (evidence: `src/shell.py`)
- Shell Engine → Command History: records commands (evidence: `src/shell.py`)
- Shell Engine → Activity Logger: logs commands (evidence: `src/shell.py`)
- Shell Engine → Configuration: loads settings (evidence: `src/shell.py`)
- File Manager → Virtual Filesystem: delegates operations (evidence: `src/filesystem.py`)
- Extra Commands → File Manager: reads virtual files (evidence: `src/extra_commands.py`)
- Extra Commands → Virtual Filesystem: traverses virtual paths (evidence: `src/extra_commands.py`)
- Extra Commands → Command Dispatcher: registers handlers (evidence: `src/extra_commands.py`)
- Configuration → Config File: loads and saves (evidence: `src/config.py`)
- Activity Logger → Log File: writes entries (evidence: `src/logger.py`)
- Shell Engine → Extra Commands: registers extra commands (evidence: `src/shell.py`)
