# shafthq/shaft_engine architecture

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

- Interactive diagram: https://gitdiagram.com/shafthq/shaft_engine
- Repository: https://github.com/shafthq/shaft_engine

## Overview

##### Project type and purpose
- This is an open-source Java/Maven test-automation engine (SHAFT Engine). It exposes a unified API for GUI (Selenium/Appium), API (REST Assured), DB, CLI, data-driven, reporting, listeners, validations, performance and tooling.
- Its purpose is to let users write high-level, fluent test code while hiding boilerplate, synchronizations, integrations (Allure, ReportPortal, Selenium Grid, cloud providers) and configuration.

##### File structure
- Top-level:
- pom.xml (Maven build)
- .github/workflows (CI: e2e tests, publish, code-scanning)
- src/main/java/com/shaft: the core engine packages
- src/main/resources: default property files, docker-compose, k8s yamls, dynamic object repo
- src/test: comprehensive test suite organized by domain
- Core packages under com.shaft:
- api: RequestBuilder, RestActions
- cli: FileActions, TerminalActions
- cucumber: BDD step definitions
- db: DatabaseActions
- driver: DriverFactory, SHAFT class (entry point)
- gui: browser & element actions plus internal image/video/locator modules
- listeners: TestNG/JUnit/Cucumber listeners + Allure, Jira helpers
- performance: LightHouse reports
- properties: engine configuration loader & helpers
- tools: IO managers (CSV, JSON, Excel, PDF), security (Google Tink), support (HTML/JS/Java helpers), TMS integrations
- validation: Fluent validations builder for REST, file, number, WebDriver element/browser validations
- Resources:
- META-INF/services (auto-configured listeners)
- docker-compose & k8s (for grid, healenium, report-portal setups)
- default properties under src/main/resources/properties

##### README for additional insights
- The tech stack calls out Java, Maven, IntelliJ, Selenium, Appium, REST Assured, OpenCV, TestNG, JUnit5, Cucumber, Allure, ReportPortal, Selenium Grid, GitHub Actions, Dependabot, CodeQL, Codacy, JaCoCo, CodeCov.
- Features: scalability (parallel, containerized, cloud), reliability (auto-sync, logging, screenshots, video), maintainability (fluent API, smart locators).
- Indicates integration points (cloud device farms: BrowserStack, LambdaTest).

##### Essential checklist
- Clear labels on each component (package or class group).
- Configuration flow from PropertiesManager to all modules.
- Listener subscription to module events and reporting outputs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Facade Layer
    subgraph "Facade Layer"
        SHAFT["SHAFT (Facade)"]:::facade
        GUI_Facade["GUI Facade\nDriverFactory"]:::facade
        API_Facade["API Facade\nRestActions"]:::facade
        DB_Facade["DB Facade\nDatabaseActions"]:::facade
        CLI_Terminal["CLI Facade\nTerminalActions"]:::facade
        CLI_File["CLI Facade\nFileActions"]:::facade
    end

    %% Engine Internals
    subgraph "Engine Internals"
        SyncManager["Synchronization Manager"]:::engine
        LocatorBuilder["Locator Builder"]:::engine
        SmartLocators["Smart Locators"]:::engine
        ImageProcessing["Image Processing"]:::engine
        VideoRecording["Video Recording Manager"]:::engine
        RequestBuilder["API Request Builder"]:::engine
        ValidationBuilder["Validation Builder"]:::engine
        ValidationExecutor["Validation Executor"]:::engine
        ReportManager["Report Manager"]:::engine
        XrayHelper["TMS Integration Helper"]:::engine
        GoogleTink["Google Tink (Security)"]:::engine
        TestNGListener["TestNG Listener"]:::engine
        JUnitListener["JUnit Listener"]:::engine
        AllureListener["Allure Listener"]:::engine
    end

    %% Configuration & Infra
    subgraph "Configuration & Infra"
        PropertiesHelper["Properties Helper"]:::config
        PropertyFileManager["Property File Manager"]:::config
        CI_CD["GitHub Actions\nDocker/K8s"]:::config
    end

    %% External Dependencies & Services
    subgraph "External Dependencies"
        WebDriverClient["WebDriver Server\n(Selenium/Appium)"]:::external
        BrowserStack["BrowserStack / LambdaTest"]:::external
        REST_API["Target REST API"]:::external
        DatabaseService["Target Database"]:::external
        FileSystem["Filesystem / CLI Env"]:::external
        AllureReport["Allure Report"]:::external
        ReportPortal["ReportPortal"]:::external
    end

    %% Interactions
    TestCode["Test Code"] -->|invokes| SHAFT
    SHAFT -->|uses| GUI_Facade
    SHAFT -->|uses| API_Facade
    SHAFT -->|uses| DB_Facade
    SHAFT -->|uses| CLI_Terminal
    SHAFT -->|uses| CLI_File

    GUI_Facade -->|calls| SyncManager
    GUI_Facade -->|builds locators| LocatorBuilder
    GUI_Facade -->|heals locators| SmartLocators
    GUI_Facade -->|processes images| ImageProcessing
    GUI_Facade -->|records video| VideoRecording
    SyncManager -->|controls| WebDriverClient
    WebDriverClient -->|drives| BrowserStack

    API_Facade -->|builds requests| RequestBuilder
    RequestBuilder -->|HTTP| REST_API

    DB_Facade -->|JDBC| DatabaseService

    CLI_Terminal -->|CLI| FileSystem
    CLI_File -->|Filesystem| FileSystem

    %% Configuration flow
    PropertiesHelper --> GUI_Facade
    PropertiesHelper --> API_Facade
    PropertiesHelper --> DB_Facade
    PropertiesHelper --> CLI_Terminal
    PropertiesHelper --> CLI_File
    PropertyFileManager --> PropertiesHelper

    %% Validation and reporting
    GUI_Facade -->|events| TestNGListener
    API_Facade -->|events| TestNGListener
    DB_Facade -->|events| TestNGListener
    CLI_Terminal -->|events| TestNGListener
    CLI_File -->|events| TestNGListener

    TestNGListener -->|hooks| AllureReport
    TestNGListener -->|hooks| ReportPortal
    JUnitListener -->|hooks| AllureReport
    AllureListener -->|lifecycle| AllureReport

    ValidationBuilder --> ValidationExecutor
    ValidationExecutor -->|validates| GUI_Facade
    ValidationExecutor -->|validates| API_Facade
    ValidationExecutor -->|validates| DB_Facade

    ReportManager -->|publishes| AllureReport
    ReportManager -->|publishes| ReportPortal
    XrayHelper --> ReportManager
    GoogleTink --> ReportManager

    CI_CD -->|runs| WebDriverClient
    CI_CD -->|deploys| Docker/K8s

    TestCode -->|configured by| PropertyFileManager

    %% Click Events
    click SHAFT "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/driver/SHAFT.java"
    click GUI_Facade "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/driver/DriverFactory.java"
    click API_Facade "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/api/RestActions.java"
    click RequestBuilder "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/api/RequestBuilder.java"
    click DB_Facade "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/db/DatabaseActions.java"
    click CLI_Terminal "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/cli/TerminalActions.java"
    click CLI_File "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/cli/FileActions.java"
    click SyncManager "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/driver/internal/DriverFactory/SynchronizationManager.java"
    click LocatorBuilder "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/gui/internal/locator/LocatorBuilder.java"
    click SmartLocators "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/gui/internal/locator/SmartLocators.java"
    click ImageProcessing "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/gui/internal/image/ImageProcessingActions.java"
    click VideoRecording "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/gui/internal/video/RecordManager.java"
    click PropertiesHelper "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/properties/internal/PropertiesHelper.java"
    click PropertyFileManager "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/properties/internal/PropertyFileManager.java"
    click TestNGListener "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/listeners/TestNGListener.java"
    click JUnitListener "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/listeners/JunitListener.java"
    click AllureListener "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/listeners/AllureListener.java"
    click ValidationBuilder "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/validation/internal/ValidationsBuilder.java"
    click ValidationExecutor "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/validation/internal/ValidationsExecutor.java"
    click ReportManager "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/tools/io/ReportManager.java"
    click XrayHelper "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/tools/internal/tms/XrayIntegrationHelper.java"
    click GoogleTink "https://github.com/shafthq/shaft_engine/blob/main/src/main/java/com/shaft/tools/internal/security/GoogleTink.java"

    %% Styles
    classDef facade fill:#ADD8E6,stroke:#000
    classDef engine fill:#90EE90,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef config fill:#D3D3D3,stroke:#000
```
