Architecture

Test Morph is a cloud-native agent deployed on Google Cloud Run, built to handle large numbers of concurrent video analysis requests without performance degradation.

---

System Overview

graph TB
    User(["User / Client"])

    subgraph TestMorph["Test Morph  (Google Cloud Run)"]
        Server["HTTP/2 Server"]
        Protocol["A2A Protocol Layer"]
        TaskMgr["Task Manager"]
        Executor["BDD Agent Executor"]
        CoreAgent["BDD Generator Agent"]
    end

    GeminiAPI(["Google Gemini AI"])

    User -->|"Video + optional text context"| Server
    Server --> Protocol
    Protocol --> TaskMgr
    Protocol --> Executor
    TaskMgr -->|"Tracks task state"| Executor
    Executor --> CoreAgent
    CoreAgent -->|"Uploads video & requests BDD generation"| GeminiAPI
    GeminiAPI -->|"Structured BDD JSON"| CoreAgent
    CoreAgent -->|"Feature files + summary"| Executor
    Executor -->|"Real-time streaming updates"| User

---

Components

HTTP/2 Server

Test Morph runs on an HTTP/2-native web server. HTTP/2 allows multiple streams to flow over a single connection simultaneously, which is essential for delivering real-time SSE (Server-Sent Events) streams — one per status update and one per generated feature file — without any blocking.

A2A Protocol Layer

This layer implements the Agent-to-Agent (A2A) Protocol v1.0. It is responsible for:

• Advertising the agent's identity and capabilities via the Agent Card
• Accepting structured requests from any A2A-compatible client
• Routing each request to the appropriate handler

Task Manager

Every request is tracked as an independent task. The task manager maintains the lifecycle state of each request — from the moment it is received until a result is returned or an error is reported. Because each video analysis is completely self-contained, tasks are ephemeral and do not persist across requests.

BDD Agent Executor

The executor bridges the A2A protocol to the actual generation logic. It:

• Extracts the video and any optional text from the incoming request
• Emits real-time status updates as the task progresses
• Orchestrates the call to the core agent
• Packages each generated feature file as a deliverable artifact
• Handles failure scenarios gracefully

BDD Generator Agent

The core intelligence of Test Morph. It:

1. Uploads your video to Gemini's File API for processing
2. Asks Gemini to analyze the video and produce structured BDD output
3. Validates and parses the response
4. Cleans up the uploaded video once processing is complete

---

Streaming Flow

Test Morph streams results back to the caller in real time via Server-Sent Events (SSE). You receive updates progressively rather than waiting for the entire generation to complete.

sequenceDiagram
    participant User
    participant TestMorph as Test Morph
    participant Gemini as Gemini AI

    User->>TestMorph: Request (video + optional context)
    TestMorph-->>User: Task received
    TestMorph-->>User: Status — Analyzing video…
    TestMorph->>Gemini: Upload video
    TestMorph->>Gemini: Generate BDD test cases
    Gemini-->>TestMorph: Structured output
    TestMorph-->>User: Status — Generating feature files…
    TestMorph-->>User: Artifact — authentication/login.feature
    TestMorph-->>User: Artifact — checkout/payment.feature
    TestMorph-->>User: Artifact — summary.json
    TestMorph-->>User: Completed

---

Request Lifecycle

flowchart LR
    A(["Incoming Request"]) --> B["A2A Protocol Layer"]
    B --> C["BDD Agent Executor"]
    C --> D{"Video present?"}
    D -- No --> E(["Failed: No video found"])
    D -- Yes --> F["Upload to Gemini"]
    F --> G["Generate BDD content"]
    G --> H["Emit feature artifacts"]
    H --> I["Emit summary"]
    I --> J(["Completed"])

---

Scalability

Test Morph is optimised for high concurrency:

Characteristic	Detail
Infrastructure	Google Cloud Run — auto-scales based on traffic
Concurrency	Up to 80 concurrent requests per instance
Scale-out	Up to 1,000 instances automatically
Request timeout	5 minutes — accommodates long videos
Minimum instances	1 — no cold starts for the first request
Video support	Up to 55 minutes of video per request (Gemini limit)

---

Error Handling

Test Morph handles all failure modes gracefully and returns a clear status message to the caller:

Failure	User-facing Message
No video in request	Prompt to provide a video file
Gemini API error	Suggestion to check credentials or quota
Unexpected AI response	Suggestion to retry the request
Network / IO error	Suggestion to check connectivity and retry