diff --git a/docs/architecture/adr-0009-external-task-job-worker.md b/docs/architecture/adr-0009-external-task-job-worker.md new file mode 100644 index 0000000..012c625 --- /dev/null +++ b/docs/architecture/adr-0009-external-task-job-worker.md @@ -0,0 +1,88 @@ +# 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. diff --git a/mkdocs.yml b/mkdocs.yml index 32e7b71..73a9a55 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,7 @@ nav: - "ADR-0006: ACL integration test provisioning": architecture/adr-0006-integration-test-provisioning.md - "ADR-0007: OpenZaak → NRC notification wiring": architecture/adr-0007-notification-wiring.md - "ADR-0008: Read projection store": architecture/adr-0008-read-projection-store.md + - "ADR-0009: External-task job worker": architecture/adr-0009-external-task-job-worker.md - Working in Gitea: gitea-workflow.md - Demo script: demo-script.md - Runbooks: