> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Understand the building blocks of Flowker: workflows, nodes, edges, catalog, provider configurations, templates, executions, and dashboard.

Flowker is built around a set of interconnected concepts. Understanding how they relate to each other helps you design, configure, and run workflows effectively. The last section on this page shows how everything connects.

## Workflows

***

A workflow is the definition of a business process — the sequence of steps Flowker follows to complete an operation.

Workflows go through a lifecycle:

| Status     | Description                              |
| ---------- | ---------------------------------------- |
| `draft`    | Created and editable. Not yet runnable.  |
| `active`   | Ready to execute. Structure is locked.   |
| `inactive` | Deactivated. No new executions accepted. |

To move a workflow between states, use the [activate](/en/reference/flowker/activate-workflow), [deactivate](/en/reference/flowker/deactivate-workflow), and [move to draft](/en/reference/flowker/move-workflow-to-draft) endpoints.

## Nodes and edges

***

Nodes are the individual steps of a workflow — what you might call **tasks** in business terms. Each node is a unit of work: receive an event, call a service, evaluate a condition, or perform an action.

Flowker supports four node types:

| Type          | Purpose                                                                                                 | When to use                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `trigger`     | Entry point for the workflow                                                                            | Always the first node. Starts execution when an event occurs.     |
| `executor`    | Calls an external service through a provider configuration                                              | When you need to call an external API or integration.             |
| `conditional` | Branches execution based on conditions                                                                  | When the next step depends on the result of a previous one.       |
| `action`      | Performs a built-in action; the available type is `set_output`, which sets the execution's final output | For setting the workflow's final output without an external call. |

**Edges** connect nodes and define the order of execution. Branching lives in the conditional node, not in the edge: the conditional node evaluates its condition and produces an outcome handle, and Flowker follows the single outgoing edge whose `sourceHandle` matches that handle. Every other node type follows all of its outgoing edges.

## Catalog

***

The catalog is the read-only registry of all built-in providers, executors, and triggers available in Flowker. You cannot create or modify catalog entries — you discover them.

Before configuring any integration, browse the catalog to see what's already available:

* **Catalog executors** are the built-in components a workflow node invokes — the generic HTTP connector, and the operations of native providers such as the Midaz ledger and Tracer. You discover them; you never create them.
* **Triggers** define the event types that can start a workflow (e.g., webhooks).

Use these endpoints to explore what's available:

* [List catalog executors](/en/reference/flowker/list-catalog-executors) and [List catalog triggers](/en/reference/flowker/list-catalog-triggers) to discover executor and trigger types.
* [List catalog providers](/en/reference/flowker/list-catalog-providers) (`GET /v1/catalog/providers`) to list all available providers.
* [Get catalog provider](/en/reference/flowker/get-catalog-provider) (`GET /v1/catalog/providers/{id}`) to get details for a specific provider.
* [List executors by provider](/en/reference/flowker/list-executors-by-provider) (`GET /v1/catalog/providers/{id}/executors`) to list the executors available for a specific provider.

## Provider configurations

***

A **provider configuration** is your connection to one live instance of an external service. It is the object a workflow node points at, and the object Flowker reads when that node runs.

Flowker separates the type of service from your connection to it:

| Concept                    | What it is                                                                 | Nature                                 |
| -------------------------- | -------------------------------------------------------------------------- | -------------------------------------- |
| **Provider**               | A type of external service (e.g., Midaz, Tracer, a generic HTTP endpoint). | Static — published in the catalog.     |
| **Provider configuration** | Your connection to one instance of that provider.                          | Dynamic — you create and manage these. |

Each provider configuration holds:

* **`config`** — the connection details for that instance, such as the base URL and authentication credentials. For the default `catalog` kind, Flowker validates this map against the catalog provider's JSON Schema. For `external_openapi`, it uses an external-OpenAPI configuration validator. Recognized sensitive leaves are written to the secrets backend and replaced by `secretRef`; legacy configurations without `secretRef` can contain inline values.
* **`allowedHosts`** — the public hosts this configuration is allowed to call.
* **`allowedPrivateHosts`** — named private hosts your operations team allows this configuration to reach. It lifts only Flowker's private or loopback restriction: if `allowedHosts` is non-empty, it must also include the host. Cloud metadata and link-local addresses stay blocked.
* **`schemaBindings`** — the XSD or OpenAPI schemas bound to this configuration, each with an optional restriction to specific OpenAPI operations.

A configuration also carries a **`kind`**. Supported values are `catalog` (the default), which connects to a catalog provider, and `external_openapi`, which connects to an OpenAPI document you uploaded yourself so a workflow node calls your own API's operations — see [Connecting your own API](/en/flowker/connecting-your-own-api).

Provider configurations have two statuses: `active` (in use) and `disabled` (temporarily offline). Use [Disable provider configuration](/en/reference/flowker/disable-provider-configuration) to take a connection out of service and [Enable provider configuration](/en/reference/flowker/enable-provider-configuration) to bring it back.

### How a workflow reaches it

Every executor node can carry a `providerConfigId` — the identifier of the provider configuration it calls through. At run time, Flowker builds each outgoing request from the base URL of that provider configuration plus the path on the node, and the node fails if the provider configuration is not `active`.

Use the [Provider configurations](/en/reference/flowker/list-provider-configurations) endpoints to create, read, update, disable, enable, and delete your connections.

## Executor configuration registry

***

Flowker keeps a registry of executor configuration records. The registry exposes four operations:

| Operation | Endpoint                                                                           |
| --------- | ---------------------------------------------------------------------------------- |
| List      | [`GET /v1/executors`](/en/reference/flowker/list-executor-configurations)          |
| Get       | [`GET /v1/executors/{id}`](/en/reference/flowker/get-executor-configuration)       |
| Update    | [`PATCH /v1/executors/{id}`](/en/reference/flowker/update-executor-configuration)  |
| Delete    | [`DELETE /v1/executors/{id}`](/en/reference/flowker/delete-executor-configuration) |

Every record carries a `status`, which the API reports in each response:

| Status         | Description                               |
| -------------- | ----------------------------------------- |
| `unconfigured` | The record has no connection details yet. |
| `configured`   | The record carries connection details.    |
| `tested`       | The record was verified.                  |
| `active`       | The record is in service.                 |
| `disabled`     | The record is out of service.             |

The update body does not include `status`, but the list operation accepts it as a query filter. Update applies to records in `unconfigured` or `configured` status; delete applies to records in `unconfigured`, `configured`, or `disabled` status. No operation in this version moves a record into `tested`, `active`, or `disabled`; the table lists those values because responses report them and the list filter accepts them.

## Templates

***

Workflow templates are pre-built workflow patterns published in the catalog. Each template describes a known integration pattern and the parameters that pattern expects.

The catalog ships the `tracer-midaz-validation` template ("Tracer Validation + Midaz Transaction"): it receives a webhook request, validates the transaction through Tracer, and creates the transaction in Midaz when Tracer approves it.

Each template has a parameter schema that defines what inputs it expects (e.g., which provider configuration to use, threshold values). When Flowker can retrieve active provider configurations, it enriches referenced parameter fields with selectable options. If lookup is unavailable or fails, it returns the original schema instead.

To inspect a template:

1. [List the catalog templates](/en/reference/flowker/list-catalog-templates).
2. [Get the template detail](/en/reference/flowker/get-catalog-template) to see its parameter schema.
3. [Validate a set of parameters](/en/reference/flowker/validate-catalog-template-params) against that schema.

## Executions

***

An execution is a runtime instance of a workflow. A trigger normally starts a new execution; a retry that reuses an existing idempotency key returns the pre-existing execution instead of creating another.

Each execution tracks:

* `executionId` — Unique identifier for this run.
* `status` — Current state: `pending`, `running`, `completed`, or `failed`.
* `stepResults` — The output of each executed executor, conditional, or action node, in order. Trigger nodes start graph traversal and do not create execution-step records.
* `finalOutput` — The final value persisted for the execution. When a `set_output` action produces an object, Flowker uses that object; otherwise it returns the accumulated workflow context.

Use [Get execution status](/en/reference/flowker/get-execution-status) to monitor progress and [Get execution results](/en/reference/flowker/get-execution-results) to retrieve the full output.

<Note>
  The status endpoint returns the execution record, including its current status. The dedicated results endpoint ([`GET /v1/executions/{id}/results`](/en/reference/flowker/get-execution-results)) returns `status`, `stepResults`, and `finalOutput` when present. A failed step can include `errorMessage`; this response has no top-level error-details field.
</Note>

## Idempotency

***

Direct execution requests require a non-empty `Idempotency-Key` string; Flowker does not enforce UUID format. The webhook header is optional.

If Flowker receives a second request with the same `Idempotency-Key`, it returns the pre-existing execution instead of creating another. A direct replay returns HTTP `200` and includes `idempotencyReplayed` in the response.

```
Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b
```

Use a new key when you intentionally want a new execution. Reuse the same key only when retrying the exact same request.

## Dashboard

***

The Dashboard API provides aggregated summaries of your workflows and executions — useful for building operational dashboards and monitoring tools. Use it whenever you need a high-level view of system health without querying individual executions.

* [Workflow summary](/en/reference/flowker/get-dashboard-workflow-summary) returns totals and breakdowns by status (draft, active, inactive).
* [Execution summary](/en/reference/flowker/get-dashboard-execution-summary) returns totals and breakdowns by status, with optional time range and status filters.

Example response from [`GET /v1/dashboards/executions`](/en/reference/flowker/get-dashboard-execution-summary):

```json theme={null}
{
  "total": 12847,
  "completed": 11903,
  "failed": 712,
  "pending": 130,
  "running": 102
}
```

Common use cases:

* **Monitoring execution health** — track completion and failure rates over time to spot degradation early.
* **Building status pages** — surface workflow throughput and success metrics in internal or client-facing dashboards.
* **Alerting on failure rate spikes** — compare `failed / total` against a threshold to trigger alerts before issues cascade.

## How it all fits together

***

Flowker's concepts build on each other in a clear sequence:

1. **Explore the catalog** to discover available providers, catalog executors, triggers, and templates.
2. **Create provider configurations** to connect Flowker to live instances of external services.
3. **Define workflows** — each executor node names a catalog executor and the provider configuration it calls through.
4. **Execute workflows** to run your business process and retrieve results.
5. **Monitor** — use the dashboard for operational summaries and the executions API for step-level detail.

Ready to see this in practice? Follow the [Getting started guide](/en/flowker/flowker-getting-started) to run your first workflow end to end.