ADR proposal · External-task job-worker pattern for the Domain Service ↔ Flowable #60

New Issue

not · 2026-06-30T14:48:18Z

not commented

2026-06-30 14:48:18 +00:00

Context

S-05 (#6) introduces the BIG Domain Service, which must orchestrate: start a Flowable registratie process → the OpenZaakAanmaken external task executes the ACL OpenZaak → the zaak URL is stored on the Registration aggregate.

The BPMN OpenZaakAanmaken task is a Flowable external-worker service task (S-03). Something has to acquire/lock that job, do the work, and complete it. This is an ADR-worthy moment per CLAUDE.md §14 (a service boundary is defined; the Workflow Client↔Flowable coupling rule §8.2 is exercised).

Decision to record

The Workflow Client (Infrastructure of the Domain Service) is the only code that talks to Flowable (§8.2). It acts as an external-task job worker (PRD §36): a hosted background worker polls Flowable for OpenZaakAanmaken jobs, locks one, calls the ACL to open a zaak (§8.1 — only the ACL talks to ZGW), attaches the resulting zaak URL to the aggregate, and completes the job. Orchestration is therefore eventually consistent, not request-synchronous.

Options considered

A — Hosted background job worker (proposed). Matches PRD §36 and the Flowable external-worker model; decouples the submit request from ACL latency.
B — Synchronous acquire+complete inside the POST /registrations request. Simpler/deterministic but couples the request to ACL latency and is not the documented pattern.

Consequences

The worker logic lives in Application (testable against fake ports); the polling loop is a thin BackgroundService in Infrastructure.
Registration persistence is in-memory for the minimal slice (the read path is fed by NRC→projection from #7); an EF-backed domain store is a documented follow-up.

ADR file docs/architecture/adr-0009-external-task-job-worker.md lands in the PR that implements #6.

## Context S-05 (#6) introduces the BIG Domain Service, which must orchestrate: start a Flowable `registratie` process → the `OpenZaakAanmaken` external task executes the ACL `OpenZaak` → the zaak URL is stored on the Registration aggregate. The BPMN `OpenZaakAanmaken` task is a Flowable **external-worker** service task (S-03). Something has to acquire/lock that job, do the work, and complete it. This is an ADR-worthy moment per CLAUDE.md §14 (a service boundary is defined; the Workflow Client↔Flowable coupling rule §8.2 is exercised). ## Decision to record The **Workflow Client** (Infrastructure of the Domain Service) is the *only* code that talks to Flowable (§8.2). It acts as an **external-task job worker** (PRD §36): a hosted background worker polls Flowable for `OpenZaakAanmaken` jobs, locks one, calls the ACL to open a zaak (§8.1 — only the ACL talks to ZGW), attaches the resulting zaak URL to the aggregate, and completes the job. Orchestration is therefore eventually consistent, not request-synchronous. ## Options considered - **A — Hosted background job worker (proposed).** Matches PRD §36 and the Flowable external-worker model; decouples the submit request from ACL latency. - **B — Synchronous acquire+complete inside the POST /registrations request.** Simpler/deterministic but couples the request to ACL latency and is not the documented pattern. ## Consequences - The worker logic lives in Application (testable against fake ports); the polling loop is a thin `BackgroundService` in Infrastructure. - Registration persistence is in-memory for the minimal slice (the read path is fed by NRC→projection from #7); an EF-backed domain store is a documented follow-up. ADR file `docs/architecture/adr-0009-external-task-job-worker.md` lands in the PR that implements #6.

not added the type:adr-proposal area:domain area:workflow labels 2026-06-30 14:49:47 +00:00

not referenced a pull request that will close this issue

2026-06-30 15:58:47 +00:00

feat(domain): BIG Domain Service skeleton with the Registration aggregate (closes #6) #61

not closed this issue

2026-07-01 08:46:22 +00:00

not referenced this issue from a commit

2026-07-01 08:46:23 +00:00

arch(domain): ADR-0009 external-task job-worker pattern (refs #6, #60)

Sign in to join this conversation.