# wix-incubator/pilot architecture

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

- Interactive diagram: https://gitdiagram.com/wix-incubator/pilot
- Repository: https://github.com/wix-incubator/pilot

## Overview

##### Main Components

- Core Library (packages/core):
- Contains the main Pilot class, which exposes APIs like start, perform, autopilot, and end.
- Implements features such as natural language test interpretation, error handling (e.g., PilotError and CodeEvaluationError), and extension of the API catalog.
- Includes utilities, common modules (e.g., APIFormatter, CodeEvaluator, logger, snapshot management), and test utilities.

- Driver Modules (packages/drivers):
- Each subfolder (e.g., detox, puppeteer, playwright, appium, basewebdriver, web-utils) represents an integration point with a specific testing framework.
- Each driver wraps and adapts the native testing APIs to work with the Pilot core.
- They typically include configuration files (e.g., tsconfig.json), examples, and driver-specific utilities (like promptHandler wrappers or custom DOM interrogation functions).

- LLM Handler / Prompt Layer:
- Although not a file per se, the README highlights that integration with an LLM service (like OpenAI or Anthropic) is fundamental.
- The PromptHandler interface and its implementations (such as CustomPromptHandler) are responsible for converting plain text commands into executable steps.

- Website / Documentation:
- The website folder holds the Docusaurus-based documentation. It isn’t part of the runtime system but is important for understanding usage and guiding enhancements.

##### Relationships and Interactions

- The Pilot instance is created in a client’s test file (see Quick Start examples).
- It depends on one of the driver modules (e.g., DetoxFrameworkDriver, PlaywrightFrameworkDriver) which translates test steps into framework-specific commands.
- It also requires a PromptHandler implementation to send and retrieve intelligent completions from an LLM service.

- Data/Control Flow:
- When a test is initiated, the Pilot class calls start() to initialize a session.
- For each test step, the perform method is called with human-readable commands.
- The Pilot class uses the PromptHandler (LLM) to convert these commands into actionable test operations.
- The selected driver interprets and executes these operations against the target application (web or mobile).

- Error Handling & Logging:
- The core module includes structured error handling and logging, which should be represented as auxiliary channels for reliability and debugging.

##### Important Architectural Patterns and Design Principles

- Plugin / Modular Driver Architecture:
- The drivers are implemented as separate modules (a clear indication of a plugin pattern) that can be easily extended or replaced.

- Separation of Concerns:
- The core (test orchestration and LLM interface) is entirely separated from platform-specific driver implementations.

- Abstraction via Interfaces:
- The use of interfaces like PromptHandler and TestingFrameworkDriver ensures loose coupling between components.

- Extensibility:
- The ability to extend the API catalog indicates a design aimed at customers who may want to add custom test commands or support for additional frameworks.

##### Relevant Technologies, Frameworks, and Tools

- Node.js and TypeScript (evident in tsconfig.json and package.json files)
- Various test frameworks: Detox (for mobile), Puppeteer and Playwright (for web), Appium (for mobile automation via WebDriverIO)
- GitHub Actions workflows for continuous integration (linting, testing, deployment)
- Docusaurus for the project website and documentation

##### Instructing the Principal Software Engineer to Include These Elements

- Data flow from user-written test steps → Pilot Core → PromptHandler → LLM Service.
- Execution flow from Pilot Core → respective Driver → target testing framework (web/mobile).
- Feedback paths, such as error logging and reporting mechanisms.

- Notes on configuration:
- How configuration (via package.json files, tsconfig.json) facilitates the integration and extension mechanism.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Engine"
        pilot["Pilot Core Engine"]:::core
        utilFormatter["APIFormatter"]:::utility
        utilEvaluator["CodeEvaluator"]:::utility
        utilLogger["Logger"]:::utility
        utilSnapshot["Snapshot Manager"]:::utility
        errorPilot["PilotError"]:::error
        errorCode["CodeEvaluationError"]:::error
        autoPerformer["AutoPerformer"]:::performer
        stepPerformer["StepPerformer"]:::performer
        corePrompt["Core PromptHandler"]:::prompt
    end

    subgraph "Driver Modules"
        detoxDriver["Detox Driver"]:::driver
        puppeteerDriver["Puppeteer Driver"]:::driver
        playwrightDriver["Playwright Driver"]:::driver
        appiumDriver["Appium Driver"]:::driver
        baseWebdriver["Base WebDriver"]:::driver
        webUtils["Web Utilities"]:::driver
        detoxPrompt["Detox PromptHandler"]:::prompt
        puppeteerPrompt["Puppeteer PromptHandler"]:::prompt
        appiumPrompt["Appium PromptHandler"]:::prompt
    end

    subgraph "External Services"
        llmService["LLM Service"]:::external
    end

    subgraph "Documentation"
        websiteDoc["Website Documentation"]:::doc
        docusaurus["Docusaurus Config"]:::doc
    end

    userTest["User Test File (Test Initiation)"]:::client

    userTest -->|"calls"| pilot

    %% Core Engine internal dependencies
    pilot -->|"utilizes"| utilFormatter
    pilot -->|"utilizes"| utilEvaluator
    pilot -->|"logsVia"| utilLogger
    pilot -->|"managesBy"| utilSnapshot
    pilot -->|"handles"| errorPilot
    pilot -->|"handles"| errorCode
    pilot -->|"invokes"| autoPerformer
    pilot -->|"invokes"| stepPerformer
    pilot -->|"integrates"| corePrompt

    corePrompt -->|"communicatesWith"| llmService

    %% Driver Modules invocation
    pilot -->|"delegatesTo"| detoxDriver
    pilot -->|"delegatesTo"| puppeteerDriver
    pilot -->|"delegatesTo"| playwrightDriver
    pilot -->|"delegatesTo"| appiumDriver
    pilot -->|"delegatesTo"| baseWebdriver
    pilot -->|"delegatesTo"| webUtils

    %% Drivers using their own PromptHandlers
    detoxDriver -->|"uses"| detoxPrompt
    puppeteerDriver -->|"uses"| puppeteerPrompt
    appiumDriver -->|"uses"| appiumPrompt

    %% Documentation reference
    pilot ---|"documentedIn"| websiteDoc
    websiteDoc --- docusaurus

    %% Click Events
    click pilot "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/Pilot.ts"
    click utilFormatter "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/common/APIFormatter.ts"
    click utilEvaluator "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/common/CodeEvaluator.ts"
    click utilLogger "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/common/logger/index.ts"
    click utilSnapshot "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/common/snapshot/SnapshotManager.ts"
    click errorPilot "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/errors/PilotError.ts"
    click errorCode "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/errors/CodeEvaluationError.ts"
    click autoPerformer "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/performers/auto-performer/AutoPerformer.ts"
    click stepPerformer "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/performers/step-performer/StepPerformer.ts"
    click corePrompt "https://github.com/wix-incubator/pilot/blob/master/packages/core/src/common/prompt-utils.ts"
    click detoxDriver "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/detox/index.ts"
    click puppeteerDriver "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/puppeteer/index.ts"
    click playwrightDriver "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/playwright/index.ts"
    click appiumDriver "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/appium/index.ts"
    click baseWebdriver "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/basewebdriver/index.ts"
    click webUtils "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/web-utils/src/index.ts"
    click detoxPrompt "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/detox/utils/promptHandler.ts"
    click puppeteerPrompt "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/puppeteer/utils/promptHandler.ts"
    click appiumPrompt "https://github.com/wix-incubator/pilot/blob/master/packages/drivers/appium/utils/promptHandler.ts"
    click websiteDoc "https://github.com/wix-incubator/pilot/tree/master/website/docs"
    click docusaurus "https://github.com/wix-incubator/pilot/blob/master/website/docusaurus.config.js"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef utility fill:#D5F5E3,stroke:#145A32,stroke-width:2px;
    classDef error fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef performer fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef prompt fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef driver fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef external fill:#D1F2EB,stroke:#138D75,stroke-width:2px;
    classDef doc fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef client fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
```
