# Workflow Engine -- Execution Model (Explanation)

## Purpose

This document explains how the workflow engine operates at runtime: -
how steps are executed - how data flows between steps - how decisions
determine the next step

------------------------------------------------------------------------

## High-Level Flow

1.  User triggers a workflow (e.g., button)
2.  Engine loads the workflow and its start step
3.  Engine creates an empty context object
4.  Steps are executed sequentially
5.  Each step may branch to another step based on its result
6.  Execution ends when no next step is defined

------------------------------------------------------------------------

## Core Components

### 1. Workflow

Defines: - name - start step

### 2. Step

Defines: - function to execute - input mapping - parameters - output key

### 3. Function

Implements the actual logic: - UI interaction (dialog, selection) -
system action (call, camera, scan) - computation

### 4. Transition

Maps a result to the next step.

### 5. Context

Shared data store during execution.

------------------------------------------------------------------------

## Context Model

The context is a key-value store:

``` json
{
  "SelectedContact": "Peter",
  "Answer": "YES"
}
```

Rules: - Steps write results using `output_key` - Later steps read
values via `input_mapping`

------------------------------------------------------------------------

## Step Execution Lifecycle

For each step:

1.  Resolve input values from context
2.  Merge with static parameters
3.  Call function
4.  Receive result:
    -   `value`
    -   `result_code`
5.  Store result in context
6.  Determine next step via transitions

------------------------------------------------------------------------

## Result Handling

A function returns:

``` json
{
  "value": "...",
  "result_code": "YES"
}
```

The `result_code` is used for branching.

Examples: - YES / NO - OK / CANCEL - PETER / NOT_PETER - ERROR

------------------------------------------------------------------------

## Transition Resolution

Order: 1. Find transition with matching `result_code` 2. If none → use
`is_default` 3. If none → end workflow

------------------------------------------------------------------------

## Example Walkthrough

### Scenario: Call Workflow

#### Step 1 -- Select Contact

Result:

``` json
{
  "value": "Peter",
  "result_code": "PETER"
}
```

→ Next step: Ask confirmation

------------------------------------------------------------------------

#### Step 2 -- Ask Confirmation

User selects YES

``` json
{
  "value": true,
  "result_code": "YES"
}
```

→ Next step: Call

------------------------------------------------------------------------

#### Step 3 -- Call Contact

Uses:

``` json
SelectedContact = "Peter"
```

→ Executes call → End

------------------------------------------------------------------------

## Error Handling

If a function fails: - return `result_code = ERROR` - transition can
handle it - or workflow stops

Optional: - retry step - fallback step - log error

------------------------------------------------------------------------

## Persistence (Optional)

During execution: - store workflow_runs - store workflow_run_steps

Benefits: - debugging - history - resume execution

------------------------------------------------------------------------

## Design Principles

-   Data-driven (no hardcoded flows)
-   Extensible (new functions)
-   Reusable (functions used in multiple workflows)
-   UI-independent (engine separated from UI)

------------------------------------------------------------------------

## Summary

Execution is a loop:

``` text
Step → Function → Result → Transition → Next Step
```

Data flows via:

``` text
Context (key-value store)
```

Control flow is defined by:

``` text
Transitions (result_code → next step)
```