eho/register-referentie
1
0
Fork 0
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

ADR: diploma upload stored in the ZGW Documenten API, fronted by the ACL (S-10b) #107

New Issue
Closed
opened 2026-07-20 09:50:52 +00:00 by not · 1 comment
not commented 2026-07-20 09:50:52 +00:00
Contributor
Copy Link
Copy Source

Context. S-10b (#103) stores an uploaded diploma in the ZGW Documenten (DRC) API and relates it to the zaak. §8.1 makes the ACL the only code that talks to ZGW. The non-obvious decisions (§14):

  1. The ACL fronts the Documenten API. A new ACL gateway method creates an enkelvoudiginformatieobject (POST /documenten/api/v1/enkelvoudiginformatieobjecten) and relates it to the zaak (POST /zaken/api/v1/zaakinformatieobjecten), mirroring the existing OpenZaakGateway patterns (Bearer ZGW JWT, LoadIntoBufferAsync for a Content-Length, no CRS headers on non-geo APIs, problem-details error surfacing). No new ZGW scopes needed (the seed applicatie has heeft_alle_autorisaties). A new informatieobjecttype is seeded in the catalogus and related to the zaaktype; its URL is injected into the ACL like ACL_ZAAKTYPE_URL.

  2. How the file bytes travel. Proposed: the browser uploads to the BFF as multipart/form-data (IFormFile) — natural for a file input; the BFF forwards to the domain and the domain to the ACL as base64 in JSON (both are JSON-only services today; a small placeholder PDF base64-encodes cheaply), and the ACL sends inhoud (base64) to the Documenten API. This keeps the existing JSON contracts on the domain/ACL and confines multipart to the portal→BFF hop. Alternative: multipart end-to-end (rejected — adds multipart plumbing to two more services for a small file).

  3. Where storing sits in the flow. The existing ProvideDocuments use case (S-10a) already completes the WachtOpDocumenten wait. S-10b makes it store the document via the ACL first, then complete the wait — so a registration only advances to beoordeling once its diploma is stored. Owner-scoping by bsn is unchanged.

  4. Scope boundary. Setting the ZGW zaak to a cancellation status on 30-day expiry is not in S-10b — carved to #106 (S-10c). S-10b is the upload-storage vertical only.

Decision to record in the ADR (lands in the PR for #103): items 1–3 as proposed; item 4 as the boundary.

Bends no §8 rule (the ACL stays the only ZGW caller; portals still only talk to the BFF). Opening per §13/§14 before coding.

**Context.** S-10b (#103) stores an uploaded diploma in the ZGW **Documenten (DRC) API** and relates it to the zaak. §8.1 makes the ACL the only code that talks to ZGW. The non-obvious decisions (§14): 1. **The ACL fronts the Documenten API.** A new ACL gateway method creates an `enkelvoudiginformatieobject` (`POST /documenten/api/v1/enkelvoudiginformatieobjecten`) and relates it to the zaak (`POST /zaken/api/v1/zaakinformatieobjecten`), mirroring the existing `OpenZaakGateway` patterns (Bearer ZGW JWT, `LoadIntoBufferAsync` for a Content-Length, no CRS headers on non-geo APIs, problem-details error surfacing). No new ZGW scopes needed (the seed applicatie has `heeft_alle_autorisaties`). A new `informatieobjecttype` is seeded in the catalogus and related to the zaaktype; its URL is injected into the ACL like `ACL_ZAAKTYPE_URL`. 2. **How the file bytes travel.** Proposed: the browser uploads to the BFF as **multipart/form-data** (`IFormFile`) — natural for a file input; the BFF forwards to the domain and the domain to the ACL as **base64 in JSON** (both are JSON-only services today; a small placeholder PDF base64-encodes cheaply), and the ACL sends `inhoud` (base64) to the Documenten API. This keeps the existing JSON contracts on the domain/ACL and confines multipart to the portal→BFF hop. Alternative: multipart end-to-end (rejected — adds multipart plumbing to two more services for a small file). 3. **Where storing sits in the flow.** The existing `ProvideDocuments` use case (S-10a) already completes the `WachtOpDocumenten` wait. S-10b makes it **store the document via the ACL first, then complete the wait** — so a registration only advances to beoordeling once its diploma is stored. Owner-scoping by bsn is unchanged. 4. **Scope boundary.** Setting the ZGW *zaak* to a cancellation status on 30-day expiry is **not** in S-10b — carved to #106 (S-10c). S-10b is the upload-storage vertical only. **Decision to record in the ADR** (lands in the PR for #103): items 1–3 as proposed; item 4 as the boundary. Bends no §8 rule (the ACL stays the only ZGW caller; portals still only talk to the BFF). Opening per §13/§14 before coding.
not added this to the Iteration 2 — Flow Completeness milestone 2026-07-20 09:50:52 +00:00
not added the type:adr-proposalarea:aclarea:portal-self-servicearea:infraarea:bff labels 2026-07-20 09:51:04 +00:00
not commented 2026-07-21 12:17:17 +00:00
Author
Contributor
Copy Link
Copy Source

Decision recorded in docs/architecture/adr-0018-diploma-upload-via-acl-documenten.md (merged with S-10b, PR #108, closing #103). Closing this ADR-proposal tracking issue as done.

Decision recorded in `docs/architecture/adr-0018-diploma-upload-via-acl-documenten.md` (merged with S-10b, PR #108, closing #103). Closing this ADR-proposal tracking issue as done.
not closed this issue 2026-07-21 12:17:17 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:acl
area:bff
area:docs
area:domain
area:event-subscriber
area:infra
area:portal-behandel
area:portal-beheer
area:portal-openbaar
area:portal-self-service
area:projection
area:workflow
type:adr-proposal
type:bug
type:chore
type:slice
No labels area:acl area:bff area:infra area:portal-self-service type:adr-proposal
Milestone
No items
No Milestone Iteration 2 — Flow Completeness
Projects
Clear projects
No projects
Assignees
Clear assignees
eho (Edwin van den Houdt)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: eho/register-referentie#107