​

Human-in-the-Loop (HITL)

​

Architecture Overview

​

1. The Block Scenario

• The Worker executes the component, which creates a Human Input Request in the database.
• The component then enters a Pending State within the Temporal workflow.
• Technically, the Temporal workflow task waits for a specific signal (resolveHumanInput).

​

2. Notification & Access

• The system generates a unique, cryptographically secure Resolve Token.
• A notification (Slack, Email) is sent with a link containing this token.
• Alternatively, the request appears in the “Pending Actions” section of the ShipSec Studio UI.

​

3. The Resume Scenario (Signal)

• The Frontend (or public link) calls the Backend API.
• The Human Input Service:
  1. Validates the input/token.
  2. Updates the request status in PostgreSQL to resolved.
  3. Calls temporalClient.signalWorkflow() with the resolveHumanInput signal.
• The blocked Temporal workflow receives the signal, resumes execution, and the manual action node returns the human’s input to the next node in the graph.

​

Sequence Diagram

┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────────┐
│ Temporal │      │  Worker  │      │ Backend  │      │   Human      │
└────┬─────┘      └────┬─────┘      └────┬─────┘      └──────┬───────┘
     │   Execute Node  │                 │                   │
     ├────────────────>│                 │                   │
     │                 │ Create Request  │                   │
     │                 ├────────────────>│                   │
     │   Signal Wait   │                 │ Notify Human      │
     │<────────────────┤                 ├──────────────────>│
     │      (PAUSED)   │                 │                   │
     │                 │                 │      Interact     │
     │                 │                 │<──────────────────┤
     │  Signal Workflow│                 │                   │
     │<──────────────────────────────────┤                   │
     │     (RESUME)    │                 │                   │
     │                 │                 │                   │

​

Security

• Token Isolation: Each request has a unique resolveToken.
• Expirations: Requests can be configured with timeouts in the Temporal workflow logic.
• Audit Log: Every resolution is tracked with respondedBy and respondedAt metadata.