> ## 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, dashboard, and audit.

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 diagram at the end of 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 via a configured executor | 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 (log, transform, etc.)   | For built-in operations that don't require external calls.    |

**Edges** connect nodes and define the order of execution. An edge can carry a condition — the next node only runs if the condition evaluates to true.

## 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:

* **Executors** are the specific capabilities you can invoke inside a workflow node (e.g., HTTP requests, data transformations).
* **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.

## Configurations

***

Before you can use an executor in a workflow, you need to configure it. An **executor configuration** defines how Flowker connects to an external service — including the base URL, authentication credentials, and the specific HTTP endpoints to call.

Executor configurations go through a lifecycle:

| Status         | Description                                             |
| -------------- | ------------------------------------------------------- |
| `unconfigured` | Created but not yet configured with connection details. |
| `configured`   | Connection details provided, ready to test.             |
| `tested`       | Connectivity test passed successfully.                  |
| `active`       | Ready to be used in workflow executions.                |
| `disabled`     | Temporarily taken out of service.                       |

Use the [Executor configurations](/en/reference/flowker/list-executor-configurations) endpoints to set up and manage your integrations.

## Provider configurations

***

Flowker uses a three-tier model for external integrations:

| Tier                       | What it is                                                             | Nature                                         |
| -------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------- |
| **Provider**               | A type of external service (e.g., Midaz, Tracer).                      | Static — defined in the catalog.               |
| **Provider Configuration** | A configured instance of a provider with credentials and a base URL.   | Dynamic — you create and manage these.         |
| **Executor Configuration** | A specific operation on a provider, with endpoints and field mappings. | Dynamic — references a provider configuration. |

A **provider configuration** connects Flowker to a live instance of an external service. You supply the base URL, authentication credentials, and any provider-specific settings. The configuration is validated against the provider's JSON Schema from the catalog.

Provider configurations have two statuses: `active` (in use) and `disabled` (temporarily offline). You can [test connectivity](/en/reference/flowker/test-provider-configuration) at any time to verify the connection is working.

Use the [Provider configurations](/en/reference/flowker/list-provider-configurations) endpoints to create, manage, and test your provider connections.

## Templates

***

Workflow templates are pre-built workflow patterns available in the catalog. Instead of defining a workflow from scratch, you can select a template, fill in its parameters, and create a ready-to-use workflow in seconds.

Each template has a parameter schema that defines what inputs it expects (e.g., which provider configuration to use, threshold values). When you retrieve a template, the schema is **dynamically enriched** — fields that reference provider configurations are populated with your active configurations, so you can pick from a dropdown instead of entering raw UUIDs.

To use a template:

1. [Browse available templates](/en/reference/flowker/list-catalog-templates) in the catalog.
2. [Get the template detail](/en/reference/flowker/get-catalog-template) to see its parameter schema.
3. Optionally [validate your parameters](/en/reference/flowker/validate-catalog-template-params) before creating.
4. [Create a workflow from the template](/en/reference/flowker/create-workflow-from-template).

The resulting workflow is created in `draft` status, so you can review and adjust it before activating.

## Executions

***

An execution is a runtime instance of a workflow. Every time you trigger a workflow, Flowker creates a new execution and processes its nodes in order.

Each execution tracks:

* `executionId` — Unique identifier for this run.
* `status` — Current state: `pending`, `running`, `completed`, or `failed`.
* `stepResults` — The output of each node that ran, in order.
* `finalOutput` — The aggregated result of the entire execution.

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 main status endpoint ([`GET /v1/executions/{id}`](/en/reference/flowker/get-execution-status)) returns `executionId`, `workflowId`, `status`, `currentStepNumber`, `totalSteps`, `startedAt`, `completedAt`, and `errorMessage`. The `stepResults` and `finalOutput` fields are only available via the dedicated results endpoint ([`GET /v1/executions/{id}/results`](/en/reference/flowker/get-execution-results)).
</Note>

## Idempotency

***

Every execution request requires an `Idempotency-Key` header. This is a UUID you generate and send with each request to uniquely identify it.

If Flowker receives a second request with the same `Idempotency-Key`, it returns the original response instead of creating a new execution. This makes retries safe — network failures and timeouts won't result in duplicate runs.

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

Always use a fresh UUID for each 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.

## Audit and compliance

***

Flowker automatically records an immutable audit trail for every significant action — workflow creation, status changes, execution starts and completions, executor calls, and configuration changes. You don't need to enable or configure anything; audit logging happens internally.

Key properties of the audit system:

* **Immutable** — audit entries are append-only and cannot be modified or deleted.
* **Hash chain integrity** — each entry includes a cryptographic hash linking it to the previous entry, making tampering detectable.
* **Flexible search** — use [Search audit events](/en/reference/flowker/search-audit-events) to query events by type, action, result, resource, or date range.
* **Chain verification** — use [Verify hash chain](/en/reference/flowker/verify-audit-hash-chain) to confirm the audit trail has not been tampered with.

## How it all fits together

***

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

1. **Explore the catalog** to discover available providers, executors, triggers, and templates.
2. **Configure providers** to connect Flowker to live instances of external services.
3. **Configure executors** to define the specific operations and endpoints your workflow needs.
4. **Define workflows** — either from scratch or from a template — referencing your executor configurations.
5. **Execute workflows** to run your business process and retrieve results.
6. **Monitor and audit** — use the dashboard for operational summaries and the audit API for compliance.

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