Overview
ark-flows-worker is the Temporal worker that runs Ark's onboarding workflows. It is a
long-running process with no HTTP API of its own (only a small health-probe server for
Kubernetes). It connects to a Temporal server, polls the onboarding-task-queue, and does two
things:
- hosts the workflow code — the parent and child workflows imported from
@digizoo/ark-flows-definitions; - implements the activities those workflows call — the activity functions are also defined
in
@digizoo/ark-flows-definitions, and they make the real HTTP calls to the Ark Platform and to Microsoft Entra ID.
The worker source itself (src/main.ts) is a thin shell: it imports the workflows, activities,
config, codec, and health server from the shared library and wires them into a Temporal Worker.
What the worker hosts and implements
The worker registers six workflows (from @digizoo/ark-flows-definitions/workflows) and twelve
activities (from @digizoo/ark-flows-definitions/activities).
| Workflow | Role | Spawned by |
|---|---|---|
onboardingIndividualWorkflow | parent | ark-flows-api via workflow.start (POST /v1/onboarding/individual) |
onboardingSoleTraderWorkflow | parent | ark-flows-api via workflow.start (POST /v1/onboarding/sole-trader) |
onboardingCompanyWorkflow | parent | ark-flows-api via workflow.start (POST /v1/onboarding/company) |
kycVerificationWorkflow | child | any parent via executeChild (id kyc-{workflowId}) |
provisioningWorkflow | child | the individual / sole-trader parent via executeChild (id provisioning-{workflowId}) |
companyProvisioningWorkflow | child | the company parent via executeChild (id provisioning-{workflowId}) — adds an addSignatories step |
The three parents share a common pre-provisioning trunk (steps 1–7: token, address, KYX,
uploads, KYC poll, risk + LOW gate) implemented in workflows/parents/_shared/pre-provisioning.ts
and differ only on the risk rule key they pass and the provisioning child they spawn.
The twelve activities the worker registers:
| Activity | What it calls |
|---|---|
getToken | Microsoft Entra ID OAuth2 client_credentials token endpoint |
updateWorkflowStatus | ark-flows-api internal POST /v1/internal/workflow-state |
lookupAddress | Ark Platform — PAF address autocomplete |
validateAddress | Ark Platform — PAF address metadata-by-id (canonical DPID record) |
initiateKyx | Ark Platform — start the KYX identity check |
uploadDocument | Ark Platform — upload an identity document |
getKyxStatus | Ark Platform — read KYX verification status |
scoreRisk | Ark Platform — BRE rule evaluation |
provisionParty | Ark Platform — provision the party |
provisionAccount | Ark Platform — provision the account |
addSignatories | Ark Platform — link the signatory party to the account (used by companyProvisioningWorkflow only) |
provisionCard | Ark Platform — provision the card |
The activity functions live in the shared library, not in this app. The worker only registers and runs them. See the library docs for each activity's internal flow.
Role in the stack
| Concern | Owned by |
|---|---|
| Workflow orchestration (step order, retries, timing) | the workflow code in @digizoo/ark-flows-definitions — the worker only hosts it |
| Side effects (token, address, KYX, risk, provision) | the activity implementations in @digizoo/ark-flows-definitions — the worker only runs them |
| Starting / observing workflows | the Ark Flows API (the REST API) |
| Durable execution, retries, scheduling | the Temporal server |
The worker must be running for any onboarding to make progress: the API only starts a workflow; Temporal dispatches its workflow and activity tasks to a connected worker, which executes them.
Two lifecycles, two homes
A single onboarding run has two distinct lifecycles:
- the business onboarding journey (
INITIATED → IN_PROGRESS → PENDING_ACTION → COMPLETED / FAILED) — what a caller sees. Documented in the Ark Flows API lifecycle. Not duplicated here. - the Temporal workflow-execution lifecycle — the parent/child execution tree, activity executions, retries, durable replay, cancellation, and terminal execution statuses. That is the worker's own lens and lives in lifecycle.
Where to read next
- lifecycle — the Temporal workflow-execution lifecycle.
- architecture — worker bootstrap, codec/DataConverter, health server.
- development — build, run, Temporal prereq, and config.
- notes — quirks and things to be aware of.