register-referentie/docs/architecture/adr-0009-external-task-job-worker.md

# ADR-0009: The Domain Service drives Flowable as an external-task job worker

- **Status:** Accepted
- **Date:** 2026-06-30
- **Deciders:** Respellion engineering
- **Relates to:** S-05 (#6); proposal #60; builds on ADR-0001 (loose coupling, §8.1/§8.2), S-03 (#4, the `registratie` BPMN), S-04 (#5, the ACL `OpenZaak` operation)

## Context

S-05 (#6) adds the **BIG Domain Service**. Submitting a registration must: create a
`Registration` aggregate, **start the Flowable `registratie` process** (S-03), have the
`OpenZaakAanmaken` task **open a zaak via the ACL** (S-04), and store the resulting zaak URL
back on the aggregate.

`OpenZaakAanmaken` is a Flowable **external-worker** service task (`flowable:type="external-worker"`,
topic `OpenZaakAanmaken`). Flowable does not push it anywhere — it parks the job and waits for a
worker to **acquire and lock** it, do the work, and **complete** it. Two coupling rules constrain
who may do what:

- **§8.2 — the Workflow Client is the only code that talks to Flowable.** BPMN models never embed
  OpenZaak knowledge; they ask the Workflow Client to execute external tasks.
- **§8.1 — the ACL is the only code that talks to ZGW.** The worker opens the zaak *through the ACL*,
  never by constructing ZGW URLs itself.

This is an ADR-worthy moment (§14): a service boundary is defined and both coupling rules are
exercised. The open question is *how* the external task is driven.

## Decision

**The Domain Service drives the `OpenZaakAanmaken` task as a hosted external-task job worker
(PRD §36). Orchestration is eventually consistent, not request-synchronous.**

- **`POST /registrations` is fast and side-effecting only on the domain side.** It creates the
  `Registration` aggregate in state `INGEDIEND`, persists it, and asks the Workflow Client to start
  one `registratie` process instance, recording the process-instance id on the aggregate. It returns
  immediately; it does **not** wait for the zaak to be opened.
- **A hosted worker polls Flowable for `OpenZaakAanmaken` jobs.** It acquires and locks a job, calls
  the ACL `OpenZaak` operation (§8.1), attaches the returned zaak URL to the matching aggregate
  (`Registration.AttachZaak`), and completes the job in Flowable. The process then runs to its end
  event.
- **The Workflow Client is the only Flowable client (§8.2).** It lives in the Domain Service's
  `Infrastructure` layer and speaks Flowable's REST API (start process-instance; acquire/lock/complete
  external-worker jobs). No other code — not the Application layer, not the BPMN — knows Flowable
  exists.
- **The worker *logic* is an Application service over ports**, not Flowable-aware code. `OpenZaakWorker`
  takes an acquired job (topic + the registration id it carries), calls `IAclClient` and
  `IRegistrationStore`, and returns the zaak URL to complete with. The **polling loop** is a thin
  `BackgroundService` in `Infrastructure` that fetches jobs via the Workflow Client and feeds them to
  the worker. So the orchestration is covered by fast unit tests against fakes; only the REST framing
  needs a container integration test.

## Scope decisions for the minimal slice

- **Registration persistence is in-memory.** The walking skeleton's *read* path is fed by
  NRC → Event Subscriber → projection (S-06, #7), not by the domain database. An EF-backed domain
  store buys nothing the demo needs yet, so it is a documented follow-up; the `IRegistrationStore`
  port keeps that change additive. (PRD §88 envisions EF Core for the domain DB eventually.)
- **The aggregate's state machine is minimal:** `INGEDIEND` on submission. Later flows (withdrawal,
  beoordeling, herregistratie) add states in their own slices — they are out of scope here.
- **No bsn flows to ZGW yet.** The ACL `OpenZaak` operation already default-fills the ZGW-mandatory
  fields (ADR-0003) and takes the bsn as its domain payload; the domain hands it through unchanged.

## Consequences

- **Positive:** the submit request is decoupled from ACL/OpenZaak latency; the documented Common
  Ground pattern (external-task worker) is realised; both coupling rules (§8.1, §8.2) hold with the
  Flowable knowledge isolated to one Infrastructure class; the orchestration is unit-testable.
- **Negative / deferred:**
  - Eventual consistency: immediately after `POST /registrations` the aggregate has no zaak URL yet.
    Acceptable — the read side is the projection, not the domain store.
  - In-memory registration state is lost on restart; fine for the skeleton, replaced by an EF store
    in a follow-up.
  - The worker polls (no push); poll interval is a tuning knob, not a correctness concern, since
    Flowable holds the job until completed.

## Alternatives considered

- **Synchronous acquire+complete inside the `POST /registrations` request** — rejected: simpler and
  deterministic, but couples the submit request to ACL/OpenZaak latency and failure, and is not the
  external-task worker pattern PRD §36 mandates. It would also make the request fail if OpenZaak is
  briefly down, instead of the job simply staying parked for the worker to retry.
- **A standalone Workflow Client service, separate from the Domain Service** — rejected for this
  slice: the worker needs the domain's aggregate store and the ACL client anyway, and PRD §9 places
  the Workflow Client inside the Domain Service deployment. A separate process adds a hop and a
  shared store for no current benefit.
- **Flowable pushes to a webhook instead of being polled** — rejected: Flowable's external-worker
  model is pull-based (acquire/lock/complete); a push shim would re-implement it with weaker
  delivery guarantees.