# qawolf/fastlane-plugin-qawolf architecture

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

- Interactive diagram: https://gitdiagram.com/qawolf/fastlane-plugin-qawolf
- Repository: https://github.com/qawolf/fastlane-plugin-qawolf

## Overview

##### Project type and purpose
- This is a Fastlane plugin written in Ruby, named `fastlane-plugin-qawolf`.
- Its purpose is to extend Fastlane with QA Wolf–specific actions:
- inject instrumentation into an iOS IPA
- upload APK/IPA/AAB artifacts to QA Wolf storage via API
- optionally trigger a QA Wolf test run via API

##### File structure
- Top‐level:
- `fastlane-plugin-qawolf.gemspec`, `Gemfile` – defines the Ruby gem
- `fastlane/` – example Fastfile demonstrating plugin usage
- `lib/fastlane/plugin/qawolf/` – plugin code:
– `actions/` – each Ruby file implements a Fastlane action (inject, upload, notify)
– `helper/` – shared utility code
– `assets/` – native instrumentation library (`instrumentation.dylib`)
- `scripts/` – standalone shell helper to inject instrumentation
- `spec/` – RSpec tests for each action

##### README for insights
- Confirms three primary actions: `inject_qawolf_instrumentation`, `upload_to_qawolf`, `notify_deploy_qawolf`.
- Describes external dependencies:
- Fastlane core
- QA Wolf HTTP API (requires `QAWOLF_API_KEY`, `QAWOLF_BASE_URL`)
- iOS code signing (for re–signing instrumented IPA)

##### Main components
- Developer’s CI/CD environment
- Fastlane core process (reads `Fastfile`, loads plugin)
- Ruby runtime + Gem (fastlane-plugin-qawolf)
- Plugin internals
- Action layer (three actions)
- Helper layer
- Asset layer (instrumentation binary)
- Shell script fallback (`inject_qawolf_instrumentation.sh`)
- External systems
- Mobile build tools (Xcode / Gradle) → produce IPA / APK / AAB
- Code signing service (re‐sign instrumented IPA)
- QA Wolf REST API →
– Artifact storage endpoint
– Test trigger endpoint
- Artifact flow
1. Fastlane lane invokes a build action → IPA/APK
2. `inject_qawolf_instrumentation` action → modifies IPA via asset or script
3. `upload_to_qawolf` action → multipart HTTP POST to QA Wolf storage
4. `notify_deploy_qawolf` action → HTTP POST to QA Wolf test‐run endpoint

##### Architectural patterns and design principles
- Plugin pattern: code is structured into discrete Fastlane actions under `actions/`.
- Separation of concerns:
- Actions handle parameter parsing & API calls
- Helper modules supply shared logic (e.g., HTTP client)
- Assets and scripts handle native instrumentation injection
- Testable units: Each action is accompanied by an RSpec test in `spec/`.

##### Essential elements to capture
- Fastlane startup: Gemfile → Pluginfile → plugin code
- Action sequence in the user’s Fastfile lane
- Native instrumentation asset or shell script
- HTTP interactions with QA Wolf (upload, notify)
- Test suite folder (`spec/`) as validation layer

## Diagram (Mermaid)

```mermaid
graph TB
    %% Developer Environment
    subgraph "Developer Environment"
        GEMSPEC["fastlane-plugin-qawolf.gemspec"]:::fastlane
        GEMFILE["Gemfile"]:::fastlane
        PLUGINFILE["fastlane/Pluginfile"]:::fastlane
        FASTFILE["fastlane/Fastfile"]:::fastlane
        FASTLANE_CORE["Fastlane Core"]:::fastlane
    end

    %% Plugin Internals
    subgraph "Plugin Code"
        ENTRY["lib/fastlane/plugin/qawolf.rb"]:::fastlane
        VERSION["lib/fastlane/plugin/qawolf/version.rb"]:::fastlane
        subgraph "Actions"
            INJECT_ACT["inject_qawolf_instrumentation_action"]:::fastlane
            UPLOAD_ACT["upload_to_qawolf_action"]:::fastlane
            NOTIFY_ACT["notify_deploy_qawolf_action"]:::fastlane
        end
        HELPER["lib/fastlane/plugin/qawolf/helper/qawolf_helper.rb"]:::fastlane
        ASSET["lib/fastlane/plugin/qawolf/assets/instrumentation.dylib"]:::tooling
        SCRIPT["scripts/inject_qawolf_instrumentation.sh"]:::tooling
    end

    %% External Systems
    subgraph "External Systems"
        BUILD["Xcode/Gradle"]:::tooling
        CODESIGN["Code Signing Service"]:::external
        API_STORAGE["QA Wolf Artifact API"]:::external
        API_TESTRUN["QA Wolf TestRun API"]:::external
    end

    %% Test Suite
    subgraph "Test Suite"
        SPEC_HELPER["spec/spec_helper.rb"]:::tests
        INJECT_SPEC["spec/fastlane/actions/inject_qawolf_instrumentation_action_spec.rb"]:::tests
        UPLOAD_SPEC["spec/fastlane/actions/upload_to_qawolf_action_spec.rb"]:::tests
        NOTIFY_SPEC["spec/fastlane/actions/notify_deploy_qawolf_action_spec.rb"]:::tests
    end

    %% CI & Config
    RAKETASK["Rakefile"]:::fastlane
    RUBOCOP[".rubocop.yml"]:::fastlane
    GITHUBCI[".github/workflows/test.yml"]:::fastlane
    TRAVISCI[".travis.yml"]:::fastlane

    %% Connections
    GEMSPEC --> FASTLANE_CORE
    GEMFILE --> FASTLANE_CORE
    PLUGINFILE --> FASTLANE_CORE
    FASTFILE --> FASTLANE_CORE
    FASTLANE_CORE --> ENTRY
    ENTRY --> VERSION
    ENTRY --> INJECT_ACT
    ENTRY --> UPLOAD_ACT
    ENTRY --> NOTIFY_ACT
    ENTRY --> HELPER
    BUILD --> INJECT_ACT
    INJECT_ACT --> ASSET
    INJECT_ACT --> SCRIPT
    INJECT_ACT --> CODESIGN
    CODESIGN --> UPLOAD_ACT
    UPLOAD_ACT --> API_STORAGE
    NOTIFY_ACT --> API_TESTRUN

    %% Test Dependencies
    SPEC_HELPER --> INJECT_SPEC
    SPEC_HELPER --> UPLOAD_SPEC
    SPEC_HELPER --> NOTIFY_SPEC
    INJECT_ACT --> INJECT_SPEC
    UPLOAD_ACT --> UPLOAD_SPEC
    NOTIFY_ACT --> NOTIFY_SPEC

    %% CI & Config to Tests
    GITHUBCI --> SPEC_HELPER
    TRAVISCI --> SPEC_HELPER
    RUBOCOP --> ENTRY
    RAKETASK --> ENTRY

    %% Click Events
    click GEMSPEC "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/fastlane-plugin-qawolf.gemspec"
    click GEMFILE "https://github.com/qawolf/fastlane-plugin-qawolf/tree/main/Gemfile"
    click ENTRY "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/lib/fastlane/plugin/qawolf.rb"
    click VERSION "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/lib/fastlane/plugin/qawolf/version.rb"
    click FASTFILE "https://github.com/qawolf/fastlane-plugin-qawolf/tree/main/fastlane/Fastfile"
    click PLUGINFILE "https://github.com/qawolf/fastlane-plugin-qawolf/tree/main/fastlane/Pluginfile"
    click INJECT_ACT "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/lib/fastlane/plugin/qawolf/actions/inject_qawolf_instrumentation_action.rb"
    click UPLOAD_ACT "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/lib/fastlane/plugin/qawolf/actions/upload_to_qawolf_action.rb"
    click NOTIFY_ACT "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/lib/fastlane/plugin/qawolf/actions/notify_deploy_qawolf_action.rb"
    click HELPER "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/lib/fastlane/plugin/qawolf/helper/qawolf_helper.rb"
    click ASSET "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/lib/fastlane/plugin/qawolf/assets/instrumentation.dylib"
    click SCRIPT "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/scripts/inject_qawolf_instrumentation.sh"
    click SPEC_HELPER "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/spec/spec_helper.rb"
    click INJECT_SPEC "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/spec/fastlane/actions/inject_qawolf_instrumentation_action_spec.rb"
    click UPLOAD_SPEC "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/spec/fastlane/actions/upload_to_qawolf_action_spec.rb"
    click NOTIFY_SPEC "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/spec/fastlane/actions/notify_deploy_qawolf_action_spec.rb"
    click GITHUBCI "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/.github/workflows/test.yml"
    click RUBOCOP "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/.rubocop.yml"
    click TRAVISCI "https://github.com/qawolf/fastlane-plugin-qawolf/blob/main/.travis.yml"
    click RAKETASK "https://github.com/qawolf/fastlane-plugin-qawolf/tree/main/Rakefile"

    %% Styles
    classDef fastlane fill:#cce5ff,stroke:#004085,color:#004085;
    classDef tooling fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef tests fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
