# bugy/script-server architecture

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

- Interactive diagram: https://gitdiagram.com/bugy/script-server
- Repository: https://github.com/bugy/script-server

## Overview

##### Project Type and Purpose
- This is a full-stack application that provides a web-based user interface for executing and managing scripts. The README emphasizes that the server lets administrators add pre-existing scripts (with various parameters and options) and provides non-technical users with an intuitive UI to execute these scripts.
- Key functionalities include script parameter handling, real‐time output, logging/auditing, authentication (LDAP, Google OAuth, etc.), alerts, and an administration panel.

##### Analyzing the File Structure
- Top-level directories such as “src” (which holds the main Python backend logic), “web-src” (the modern frontend portion implemented likely with Vue or other frameworks), “tools” (deployment and auxiliary build scripts), “samples” (demonstration configs and scripts), and “conf” (configuration files) are all major indicators.
- Within “src”, note the modularity:
- “auth” contains various authentication/authorization strategies (OAuth variants, LDAP, htpasswd, etc.).
- “communications” encapsulates alerting and communications modules (e.g., email, HTTP-based, or script-triggered destinations).
- “execution” and “config” modules handle core aspects of running and configuring scripts.
- “scheduling” is used for managing job schedules.
- “model” defines data models for script configurations, user files, logging, etc.
- “web” holds server and client-related logic for handling HTTP requests with Tornado.
- “web-src” includes modern web components, such as an admin interface and main application components, stylesheets, and unit tests, which build the client-side UI.

##### Using README insights
- The README clarifies that the server supports several configurable script parameters, real-time script execution output, and extensive logging. There is an administration panel reachable via a dedicated HTML page and instructions for both production and development setups.
- The README also notes external integrations (LDAP, OAuth, Docker support) and multiple configuration options which should be represented as configurable “injection” points within the architecture.

a. Main Components:
- Backend Application Server (Python/Tornado): Includes sub-modules for authentication, script configuration/service, execution management, scheduling, and logging.
- Script Execution Service: Responsible for launching and managing script processes (using Popen, PTY, etc.) and handling their output/alerts.
- Configuration Service: Manages script settings, parameters, and configuration validation.
- Communications/Alerting Service: Handles notifications (email, HTTP, etc.) and real-time output updates.
- Frontend UI: Separated into at least two parts – the public client UI and the Administration panel. The frontend is built with modern web technologies (visible in the “web-src” folder, which includes Vue components, routers, and state stores).
- Integration/External Services: Authentication providers (Google OAuth, LDAP, etc.), potential external file storage (for logs and uploaded files), and email/HTTP integrations.
- Testing/Deployment Tools: E2E and unit tests, Docker and virtualenv deployment tools.

b. Relationships and Interactions:
- The Client Browser interacts with the Frontend UI (both Admin and main apps) which make API calls to the backend web server.
- The Backend Server processes HTTP requests with Tornado, delegates authentication (via various auth modules), obtains script configurations, and triggers script executions.
- Script Execution Service acts as a sub-system that receives commands from the main server and runs the scripts, sending back real-time output (which in turn is relayed to the frontend).
- The Configuration Service feeds the execution engine and UI with precise parameters and validation rules, while the Communications module sends alerts and logs events.
- There are deployment pipelines and auxiliary tools that interact with both the source code and the build/deploy process (as seen under “tools”).

c. Architectural Patterns and Design Principles:
- Modular Separation: Code is organized in modules for authentication, execution, configuration, scheduling, etc.
- Separation of Concerns: The backend (Python) and frontend (web-src) are clearly delineated, with distinct responsibilities.
- Plugin/Extension Points: Numerous authentication methods and script configuration options allow extension without deep changes.
- Real-time Data Flow: Emphasize the data flow between the execution service and the client UI (for real-time output updates).
- Robust Error Logging and Auditing: The logging subsystem with separate logs per script execution.

d. Relevant Technologies and Frameworks:
- Python 3.7+ with Tornado web server (backend).
- Frontend technologies include JavaScript, HTML, CSS, Vue (as implied by *.vue files and package.json in web-src).
- Testing frameworks (pytest, etc.) are present in “src/tests” and “web-src/tests”.
- Deployment tools (Docker, travis CI, shell scripts) are used for CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        Client["Client Browser"]:::external
        Frontend["Frontend UI (Admin/Main)"]:::frontend
    end

    subgraph "Backend Layer"
        Backend["Backend Application Server"]:::backend
        Auth["Authentication Module"]:::backend
        Execution["Script Execution Service"]:::backend
        Config["Configuration Service"]:::backend
        Comm["Communications & Alerts"]:::backend
        Sched["Scheduling Module"]:::backend
        Models["Data Models & Configurations"]:::backend
    end

    subgraph "Deployment & Tools"
        Tools["Deployment & Auxiliary Tools"]:::tools
    end

    subgraph "External Integrations"
        ExtAuth["External Auth Providers"]:::external
        ExtServices["Email/HTTP Services"]:::external
    end

    Client -->|"API_calls"| Frontend
    Frontend -->|"HTTP_requests"| Backend
    Backend -->|"delegates"| Auth
    Backend -->|"triggers"| Execution
    Backend -->|"retrieves_config"| Config
    Backend -->|"sends_alerts"| Comm
    Backend -->|"manages_schedule"| Sched
    Backend -->|"uses_models"| Models
    Execution -->|"real-time_output"| Frontend
    Auth -->|"integrates"| ExtAuth
    Comm -->|"integrates"| ExtServices
    Tools -->|"deployment_scripts"| Backend

    click Backend "https://github.com/bugy/script-server/blob/master/src/main.py"
    click Backend "https://github.com/bugy/script-server/blob/master/src/web/server.py"
    click Auth "https://github.com/bugy/script-server/tree/master/src/auth"
    click Execution "https://github.com/bugy/script-server/tree/master/src/execution"
    click Config "https://github.com/bugy/script-server/tree/master/src/config"
    click Comm "https://github.com/bugy/script-server/tree/master/src/communications"
    click Frontend "https://github.com/bugy/script-server/tree/master/web-src"
    click Sched "https://github.com/bugy/script-server/tree/master/src/scheduling"
    click Models "https://github.com/bugy/script-server/tree/master/src/model"
    click Tools "https://github.com/bugy/script-server/tree/master/tools"

    classDef backend fill:#FAD7A0,stroke:#333,stroke-width:2px;
    classDef frontend fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef tools fill:#D5F5E3,stroke:#333,stroke-width:2px;
```
