# rasukarusan/shellnium architecture

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

- Interactive diagram: https://gitdiagram.com/rasukarusan/shellnium
- Repository: https://github.com/rasukarusan/shellnium

## Overview

##### Project type and purpose
- Shellnium is a command-line automation library (a WebDriver wrapper) for Bash/Zsh.
- It provides high-level Bash functions that map to the WebDriver HTTP API, letting users write browser automation scripts entirely in shell.

##### File structure
- Top level:
- demo.sh, demo2.sh, demo3.sh – example client scripts
- lib/ – the reusable library code
– core.sh: implements the main WebDriver session, navigation, element/state/document APIs
– selenium.sh: high-level entry point that sources core.sh and util.sh, defines user-facing functions
– util.sh: helper functions (HTTP calls via curl, JSON handling via jq, error handling)
- No frontend/backend split; this is a library that communicates with an external WebDriver server.

##### README for additional insights
- Dependencies: Bash or Zsh, jq, ChromeDriver (Selenium server) + Google Chrome, optionally iTerm2/AppleScript for demo2.
- Usage pattern:
- User script sources selenium.sh
- Calls functions like new_session, navigate_to, find_element, send_keys, etc.
- Under the hood: these shell functions construct and issue HTTP requests to ChromeDriver’s JSON-Wire or W3C WebDriver endpoint, parse JSON responses, return values to the caller.

##### Detail
- Optional/demo flows (demo2 AppleScript) as extensions so that the core library remains uncluttered.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Script Layer
    Demo1("demo.sh"):::script
    Demo2("demo2.sh"):::script
    Demo3("demo3.sh"):::script

    %% Optional Demo Extension
    subgraph "Optional Demo Extensions"
        direction TB
        AppleScript["iTerm2 & AppleScript"]:::optional
    end

    %% Shellnium Library Layer
    subgraph "Shellnium Library"
        direction TB
        Selenium["selenium.sh - Entry Point"]:::library
        Core["core.sh - WebDriver API Implementations"]:::library
        Util["util.sh - HTTP & JSON Helpers"]:::library
    end

    %% External Services
    ChromeDriver["ChromeDriver (WebDriver Server)"]:::external
    Chrome["Google Chrome Browser"]:::external

    %% Interactions
    Demo1 -->|"sources & calls"| Selenium
    Demo3 -->|"sources & calls"| Selenium
    Demo2 -->|"sources & calls"| Selenium
    Demo2 -->|"invokes"| AppleScript

    Selenium -->|"delegates to"| Core
    Core -->|"uses for HTTP & JSON"| Util

    Util -->|"curl POST /session, etc."| ChromeDriver
    ChromeDriver -->|"WebDriver commands"| Chrome
    ChromeDriver -->|"JSON responses"| Util

    %% Click Events
    click Demo1 "https://github.com/rasukarusan/shellnium/blob/master/demo.sh"
    click Demo2 "https://github.com/rasukarusan/shellnium/blob/master/demo2.sh"
    click Demo3 "https://github.com/rasukarusan/shellnium/blob/master/demo3.sh"
    click Selenium "https://github.com/rasukarusan/shellnium/blob/master/lib/selenium.sh"
    click Core "https://github.com/rasukarusan/shellnium/blob/master/lib/core.sh"
    click Util "https://github.com/rasukarusan/shellnium/blob/master/lib/util.sh"

    %% Styles
    classDef script fill:#f9e79f,stroke:#b9770e,color:#000
    classDef library fill:#aed6f1,stroke:#1f618d,color:#000
    classDef external fill:#abebc6,stroke:#239b56,color:#000
    classDef optional fill:#fdf2e9,stroke:#cd6155,stroke-dasharray: 5 5,color:#000
```
