# eoli3n/shellcast architecture

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

- Interactive diagram: https://gitdiagram.com/eoli3n/shellcast
- Repository: https://github.com/eoli3n/shellcast

## Overview

##### Project Overview
- Project Type: A real‑time streaming Node.js application.
- Purpose: To execute shell commands, stream the outputs in realtime, and display them in both formatted (console) and unformatted (plain text) views with argument handling and ANSI “rainbow” output highlighting.
- Deployment: It is designed to be deployed behind an Nginx reverse proxy (as shown in the README) and also can be managed via systemd.

##### Main Components
a. Client/Browser:
– Represents the end user’s browser or curl client.
– Two distinct views: “Console” (HTML with styling) and “Plain” (raw text output).
– Uses static assets (from the public directory) such as CSS for styling and JavaScript (client.js, ansi_up.js) for parsing ANSI escape codes.
b. Reverse Proxy (Nginx):
– Accepts incoming HTTPS requests.
– Routes traffic with path /shellcast/ to the Node.js backend.
– Manages SSL termination and additional headers.
c. Node.js Backend (shellcast.js):
– Core application handling the streaming. This is the main entry point.
– Loads its configuration from a YAML file (config-sample.yml copied to config.yml).
– Handles URL endpoints such as /shellcast/rainbow and /shellcast/args, determining whether to return “console” or “plain” output.
d. Shell Scripts (tests folder):
– These are examples (e.g., rainbow.sh, args.sh) demonstrating the output that can be streamed.
– Although these scripts are part of testing/demonstration, they hint at how the backend streams shell outputs.
e. Views:
– Contains HTML templates (e.g., views/index.html, views/plain/index.html) used by the backend to render the output to the browser.
f. Deployment & Process Management:
– systemd service unit (shellcast.service) details how the Node.js process is initiated and managed.
– Configuration files like config-sample.yml and environmental variables (NODE_PORT, SUBDIR) are used to manage runtime settings.

##### Relationships and Interactions
- The Client sends a request (HTTP/HTTPS) which is first caught by the Nginx reverse proxy.
- Nginx proxies the request to the Node.js application running on port 3000.
- The Node.js backend then executes the necessary shell command (via the scripts or internally) and streams its output back.
- Depending on the request (console vs. plain), the backend renders the view from the “views” directory and enhances it with static assets (from “public”).
- The end-user sees the streamed output in real time with proper ANSI highlighting, facilitated by client-side JS (ansi_up.js) if needed.
- Optionally, the systemd service configuration ensures the app runs as a managed background service.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different directories for views, static assets, and test scripts illustrate a separation between presentation and logic.
- Reverse Proxy: Use of Nginx as a reverse proxy segregates public HTTPS routing from backend processing.
- Environment Configuration: The system uses config files and environment variables to separate deployment concerns (e.g., NODE_PORT, SUBDIR).
- Modularity: The project’s modular file tree (with separate shells for test cases and static file resources) shows an architecture that can be easily extended or maintained.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client/Browser (Console & Plain Views)"]:::client
    Nginx["Nginx Reverse Proxy (SSL Termination & /shellcast routing)"]:::nginx
    Client -->|"HTTPS"| Nginx

    subgraph "Node.js Backend Layer"
        BN["Node.js Backend (shellcast.js)"]:::node
        subgraph "Static Assets"
            CSS["CSS Files"]:::static
            JS["JS Files"]:::static
        end
        CFG["Configuration (config-sample.yml)"]:::config
        Tests["Shell Scripts (tests)"]:::shell
        VWS["Views Templates (views)"]:::views
        EPArgs["Endpoint:/shellcast/args"]:::endpoint
        EPRainbow["Endpoint:/shellcast/rainbow"]:::endpoint
        DEP["Process Management (systemd)"]:::deploy
    end

    Nginx -->|"Proxies_to_port_3000"| BN
    BN -->|"Serves_static_files"| CSS
    BN -->|"Serves_static_files"| JS
    BN -->|"Loads_config"| CFG
    BN -->|"Executes_shell_commands"| Tests
    BN -->|"Handles_endpoints"| EPArgs
    BN -->|"Handles_endpoints"| EPRainbow
    BN -->|"Renders_views"| VWS
    DEP -->|"Manages"| BN
    VWS -->|"Delivers_rendered_view"| Client
    BN -->|"Streams_output"| Client

    click BN "https://github.com/eoli3n/shellcast/blob/master/shellcast.js"
    click CFG "https://github.com/eoli3n/shellcast/blob/master/config-sample.yml"
    click Tests "https://github.com/eoli3n/shellcast/tree/master/tests"
    click VWS "https://github.com/eoli3n/shellcast/tree/master/views"
    click CSS "https://github.com/eoli3n/shellcast/tree/master/public/css"
    click JS "https://github.com/eoli3n/shellcast/tree/master/public/js"

    classDef client fill:#bbdefb,stroke:#000,stroke-width:1px
    classDef nginx fill:#c8e6c9,stroke:#000,stroke-width:1px
    classDef node fill:#ffe082,stroke:#000,stroke-width:1px
    classDef static fill:#d1c4e9,stroke:#000,stroke-width:1px
    classDef config fill:#f8bbd0,stroke:#000,stroke-width:1px
    classDef shell fill:#ffccbc,stroke:#000,stroke-width:1px
    classDef views fill:#b2dfdb,stroke:#000,stroke-width:1px
    classDef endpoint fill:#dcedc8,stroke:#000,stroke-width:1px
    classDef deploy fill:#c5cae9,stroke:#000,stroke-width:1px
```
