atomic-design-poc/docs/prd/0001-mijn-aanvragen-en-wizardstatus.md

# PRD 0001 — "Mijn aanvragen": running wizards, application status & document preview

Status: Proposed · Date: 2026-07-01 · Context: SSP / Zorgverlener (see ADR-0002)

> Cross-references: **ADR-0001** (BFF-lite endpoints + decision DTOs) and **ADR-0002** (user groups as
> actors; the `Concept → In behandeling → Goedgekeurd/Afgewezen` aanvraag lifecycle). This PRD
> _materializes_ that lifecycle as a backend-owned aggregate — still entirely within the Zorgverlener
> self-service context; the Behandelaar/backoffice app that advances manual cases stays a separate,
> unbuilt context.

---

## 1. Problem

A logged-in Zorgverlener cannot see what they have started or submitted, and cannot review what they
uploaded. Concretely, today:

- Wizard drafts live in **per-wizard `sessionStorage`** (`registratie-v2`, `intake-v3`); the
  **herregistratie wizard has no persistence at all**. Nothing enumerates "my in-progress applications."
- There is **no application list** — only a single optimistic boolean, `pendingHerregistratie`, in
  `src/app/registratie/application/big-profile.store.ts:53`, surfaced as one dashboard alert.
- Uploaded documents **cannot be previewed or downloaded**. The backend `DocumentStore`
  (`backend/src/BigRegister.Api/Data/DocumentStore.cs`) deliberately stores **metadata only, no bytes**,
  and there is **no GET-content endpoint**.
- A **manual diploma is hard-rejected**: `SubmissionRules.RejectRegistratie("handmatig")` returns a
  422 (`backend/src/BigRegister.Api/Domain/Submissions/SubmissionRules.cs`). The product wants such a
  submission to _succeed_ and sit in a pending (manual-review) state instead.

## 2. Goals

1. Show **all running (concept) applications** as dynamic blocks at the **top of the dashboard**, so the
   user immediately sees what they initiated, with **Verder gaan** (resume) and **Annuleren** (cancel →
   start fresh).
2. On **re-opening** a concept wizard, let the user **preview/download** the documents they already
   uploaded.
3. Show **submitted-but-unprocessed** applications in a **pending** state on the dashboard.
4. Provide **two registratie flows** that both submit successfully (never disallow submission):
   - **Auto-approved** (`diplomaHerkomst = 'duo'`) → resolves to **Goedgekeurd**.
   - **Manual backoffice** (`diplomaHerkomst = 'handmatig'`) → stays **In behandeling** (pending).
5. Make the backend the **system of record** for applications (concept + submitted), per the chosen
   architecture.

## 3. Non-goals / Out of scope (POC)

- The **Behandeling/backoffice application** that advances manual aanvragen (ADR-0002). Manual cases
  stay pending forever in this build.
- Real auth / multi-user — a single `DemoOwner` owns everything (matches the faked DigiD session).
- Real blob storage, virus scanning, retention — document **bytes are held in-memory** and reset when
  the backend restarts.
- **Withdrawing** a submitted aanvraag ("intrekken") — cancel applies to concepts only.
- Document preview for the **dev upload simulation** (`?scenario=upload-slow|upload-fail`) — that path
  returns a fake `demo-*` documentId with no bytes; preview requires a real upload.

## 4. Personas

Single actor: the **Zorgverlener** (healthcare professional, DigiD/BSN, self-service). Per ADR-0002,
"who may advance a manual application" is the **Behandelaar**, an actor in a _separate_ backoffice
context that is not part of this app.

## 5. Domain model — the `Aanvraag` aggregate (backend-owned)

The backend gains an `Aanvraag` (application) aggregate — the system of record the dashboard reads.

| Field                                      | Type                                          | Notes                                                                      |
| ------------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------- |
| `id`                                       | string (uuid)                                 | client-visible handle; used in the resume deep link                        |
| `type`                                     | `registratie` \| `herregistratie` \| `intake` | which wizard                                                               |
| `status`                                   | discriminated union (below)                   | computed on read for auto-approval                                         |
| `draft`                                    | opaque JSON                                   | the wizard's persisted machine snapshot (Concept only)                     |
| `stepIndex`, `stepCount`                   | int                                           | for the "Stap X van Y" progress on the block                               |
| `documentIds`                              | string[]                                      | documents linked to this aanvraag                                          |
| `referentie`                               | string?                                       | set on submit (e.g. `BIG-2026-456789`)                                     |
| `owner`                                    | string                                        | `DemoOwner`                                                                |
| `autoApprovable`                           | bool                                          | set at submit: `diplomaHerkomst === 'duo'` (registratie); other types auto |
| `createdAt` / `updatedAt` / `submittedAt?` | timestamps                                    |                                                                            |

### Status lifecycle

```mermaid
stateDiagram-v2
    [*] --> Concept: create (first wizard step)
    Concept --> Concept: draft sync (per step)
    Concept --> [*]: Annuleren (cancel, delete)
    Concept --> InBehandeling: submit (accepted)
    Concept --> Afgewezen: submit invalid (e.g. 0 uren)
    InBehandeling --> Goedgekeurd: auto (duo) after processing window Δ
    InBehandeling --> InBehandeling: manual (handmatig) — awaits backoffice (not built)
    Goedgekeurd --> [*]
    Afgewezen --> [*]
```

FE-mirrored discriminated union (illegal states unrepresentable, same reflex as `RemoteData`):

```ts
type AanvraagStatus =
  | { tag: 'Concept'; stepIndex: number; stepCount: number }
  | { tag: 'InBehandeling'; referentie: string; manual: boolean } // manual=true → "wordt beoordeeld"
  | { tag: 'Goedgekeurd'; referentie: string }
  | { tag: 'Afgewezen'; referentie: string; reden: string };
```

### Deterministic auto-approval (no background timer)

Auto-approval is **computed on read**: for an `autoApprovable` aanvraag, if
`now > submittedAt + PROCESSING_WINDOW` (≈8s) the status reports **Goedgekeurd**, else **In behandeling**.
Manual (`autoApprovable === false`) aanvragen never auto-advance. This yields a visible
pending→approved transition for the auto flow and a persistent pending for the manual flow, with no
timers or background jobs — purely a function of stored timestamps.

## 6. UX

### Dashboard — new "Mijn aanvragen" section (top, above "Wat moet ik regelen")

Renders `ApplicationsStore.applications()` through `<app-async>` as a list of **blocks**, sorted:
Concept → In behandeling → resolved. Empty list → the section is hidden.

Per-status block (new `aanvraag-block` component; **which** actions/badge a block shows comes from a
pure `blockActions(status)`):

| Status             | Badge                  | Body                                                                                 | Actions                                          |
| ------------------ | ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------ |
| **Concept**        | grey "Concept"         | wizard type + "Stap X van Y"                                                         | **Verder gaan** (resume), **Annuleren** (cancel) |
| **In behandeling** | amber "In behandeling" | referentie + ingediend-datum; manual → "wordt handmatig beoordeeld in de backoffice" | view/preview documents                           |
| **Goedgekeurd**    | green "Goedgekeurd"    | referentie                                                                           | —                                                |
| **Afgewezen**      | red "Afgewezen"        | referentie + reden                                                                   | —                                                |

- **Verder gaan** deep-links to the wizard with `?aanvraag=<id>`; the wizard loads the draft from the
  backend and seeds its machine.
- **Annuleren** confirms, then `DELETE /applications/{id}` (removes the aanvraag and its unlinked
  documents); the block disappears and the user can start a new one from the existing action cards.

### Document preview/download

`document-chip` (completed uploads) gains a **"Voorbeeld / Download"** affordance linking to
`GET /api/v1/uploads/{documentId}/content` — opens inline for `application/pdf` and images, downloads
otherwise. Available both inside the wizard (Concept) and from an In-behandeling block's document view.

## 7. Backend design (ASP.NET Core, in-memory — extends existing patterns)

- **`ApplicationStore`** (new, mirrors `DocumentStore`): in-memory dict + lock; create/get/list/
  upsert-draft/delete; `Submit()` transition; status computed on read (auto-approval window).
- **Endpoints** (`Program.cs`, `/api/v1`):
  - `GET /applications` → `List<ApplicationSummaryDto>` for the owner.
  - `GET /applications/{id}` → `ApplicationDetailDto` (includes `draft` to resume).
  - `POST /applications` → create Concept (returns id); `PUT /applications/{id}` → draft sync (idempotent).
  - `DELETE /applications/{id}` → cancel Concept (cascades to unlinked documents).
  - `POST /applications/{id}/submit` → runs `SubmissionRules`, sets `autoApprovable`, transitions to
    In behandeling (or Afgewezen), links documents, returns `{ referentie, status }`.
- **`SubmissionRules` change**: `handmatig` no longer 422s — it yields `autoApprovable = false`
  (manual/pending). Keep genuine validation rejects (0 uren → Afgewezen).
- **`DocumentStore` change**: store `byte[] Content` + `string ContentType`; add
  `GET /uploads/{documentId}/content` returning bytes (Content-Disposition inline for pdf/image,
  attachment otherwise). The multipart `POST /uploads` now captures bytes + content-type.
- **Tests** (`dotnet test`): lifecycle (concept→submit→auto/manual/afgewezen), auto-approve-on-read
  window boundary, content endpoint returns bytes+type, cancel cascades to unlinked docs only.

## 8. Frontend design (Angular — TEA + atomic + BFF-lite)

- **Contracts** (`contracts/`): `ApplicationSummaryDto`, `ApplicationDetailDto`, `AanvraagStatusDto`.
- **`applications.adapter.ts`** (`infrastructure/`, the only new network surface): `httpResource` for
  the list + commands (create/sync/delete/submit), with a hand-written `parseApplication*` boundary
  (DTO→domain), per ADR-0001. Upload adapter gains a `contentUrl(documentId)` helper.
- **`ApplicationsStore`** (`application/`, `providedIn: 'root'`): `applications` RemoteData list rendered
  via `<app-async>`; optimistic begin/confirm/rollback around cancel + submit; `reload()` after
  mutations — same pattern as `BigProfileStore`. Dashboard polls/reloads to reflect auto-approval.
- **Wizards**: replace `sessionStorage` persistence with a **debounced backend draft-sync** command on
  each step change; open via `?aanvraag=<id>` (load detail → seed the machine). Apply the same to the
  herregistratie wizard (it gains persistence). The registratie machine already carries
  `diplomaHerkomst`, which flows into the submit payload to set `autoApprovable`.
- **Domain**: FE `AanvraagStatus` union + pure `blockActions(status)` (badge + allowed actions);
  co-located `*.spec.ts`.
- **UI (atomic, mostly composition)**: new `aanvraag-block`; new "Mijn aanvragen" dashboard section;
  `document-chip` preview/download affordance. Reuse existing atoms (`card`, `button`, `alert`,
  `heading`, status-icon/badge). All user-facing copy via `$localize`; shared/English components stay
  language-agnostic (props with localizable defaults). Stories for each block status + chip preview
  (a11y addon on).

## 9. Delivery phases

Each phase must leave every gate green (`npm run lint`, `npm test`, `npm run build`,
`cd backend && dotnet test`). Build the **registratie vertical slice first**; herregistratie/intake
blocks are the same pattern copied.

- **A — Backend Aanvraag store + endpoints + lifecycle** (+ auto-approve-on-read) + tests.
- **B — Backend document bytes + `GET /uploads/{id}/content`** + tests.
- **C — Contracts + adapters** (applications parse boundary; upload content URL).
- **D — `ApplicationsStore` + wizard backend draft-sync + resume-by-link** (retire sessionStorage keys).
- **E — FE `AanvraagStatus` union + `blockActions` + registratie two-flow wiring + herregistratie persistence.**
- **F — Dashboard "Mijn aanvragen" blocks + `document-chip` preview affordance** + stories.

## 10. Testing / verification

Unit (co-located): `blockActions`, `AanvraagStatus` transitions, `parseApplication*` boundary; backend
`ApplicationStore` lifecycle + auto-approve window + content endpoint + cancel cascade. UI via Storybook
stories. End-to-end demo:

1. `docker compose up` (Swagger at `:5000/swagger`) or `npm start` + backend; log in.
2. Start each wizard partway → blocks appear at the top of the dashboard (Concept, "Stap X van Y").
3. Reopen a Concept → previously uploaded documents **preview/download** (real upload, not `?scenario=upload-*`).
4. **Annuleren** a Concept → block disappears; start a fresh one.
5. Registratie with **DUO** diploma → submit → block shows **In behandeling**, then **Goedgekeurd**
   after the processing window (on dashboard reload).
6. Registratie with **handmatig** diploma → submit (not blocked) → block stays **In behandeling**
   ("wordt handmatig beoordeeld").

## 11. Risks & notes

- **Retiring sessionStorage** changes existing wizard behavior; ensure resume-by-link and draft-sync
  cover the previous "reload keeps progress" guarantee. Bump/remove the old `registratie-v2` / `intake-v3`
  keys (no migration — ponytail).
- **Chatty sync**: debounce the per-step `PUT /applications/{id}`; keep it optimistic so typing stays snappy.
- **Dev simulation** uploads have no bytes → hide the preview affordance when the documentId is a
  `demo-*` sentinel (or when content 404s).
- **In-memory reset**: backend restart clears all aanvragen/documents — acceptable for the POC; call it
  out so testers aren't surprised.

ponytail: the only genuinely new pieces are the backend `Aanvraag` store, document byte storage, and
the `aanvraag-block` component. Everything else reuses existing store/adapter/`<app-async>`/atom
patterns. Don't build the backoffice, real storage, or withdrawal — YAGNI until asked.