User story: permit-to-payment guided public administration process #9

New Issue

zemion · 2026-07-14T14:06:34+02:00

zemion commented

2026-07-14 14:06:34 +02:00

User Story

As a resident or applicant, I want to apply for a permit through a public portal, upload the required evidence, follow the status of my application, attend any required appointment, receive the generated permit or decision, and complete payment where required, so that the whole administrative process is understandable and reliable.

As an internal case worker, I want GovOPlaN to create the right case, workflow, tasks, evidence links, appointments, generated documents, communications, payment evidence, and audit trail automatically or semi-automatically, so that I can focus on review and decisions instead of manually coordinating every system step.

Reference Journey

This is the previously documented permit-to-payment story. It is the Wave 1 reference process in govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md and is also tracked by add-ideas/govoplan-core#214 as the configuration-package implementation target.

A person applies for a permit through the public portal.
Forms runtime receives the submission, validation result, attachments, and submission evidence.
Workflow starts a process instance and asks cases to create a durable case record.
Files/DMS links uploaded evidence to the case.
Tasks assigns intake/review work to the responsible role or function.
Workflow moves the case through intake, review, appointment/booking, decision, document generation, communication, payment, and closure.
Templates/DMS generates the permit or rejection/decision document.
Postbox, mail, and notifications inform the applicant and internal actors.
Calendar, appointments, or booking handle appointment handoff where needed.
Payments, ledger, and XRechnung record payment and accounting evidence.
Audit and records retain the trace of decisions, generated artifacts, communications, and retention state.

Product Shape

The story should become an installable demo/configuration package that wires existing modules into one complete public-administration process. The package should configure the involved forms, case type, workflow definition, task queues, document templates, appointment/payment handoffs, notifications, and user-facing documentation.

The operator experience should be guided: users should see where they are in the process, which action is pending, what evidence exists, what the next module handoff will do, and how to return to the process after leaving it.

Module Touchpoints

Likely participating modules:

module/portal: public entry point and applicant-facing status surface.
module/forms: application form, validation, drafts, submission evidence.
module/files: uploaded evidence and generated artifact links.
module/cases: durable administrative case record.
module/workflow: state machine, handoffs, waits, retries, and progress.
module/tasks: internal review and follow-up tasks.
module/templates: permit/decision document generation.
module/permits: permit/license domain records and lifecycle semantics.
module/postbox, module/mail, module/notifications: applicant and internal communication.
module/calendar, module/appointments: appointment/booking handoff.
module/payments, module/ledger, module/xrechnung: payment and accounting evidence.
module/audit, module/records: traceability and retention.

Acceptance Criteria

A permit-to-payment configuration package can be installed in a local demo environment.
The package creates or references the needed form, case type, workflow definition, task queues, templates, notification rules, and handoff settings.
An applicant can submit a permit application with evidence through the portal/forms path.
The submission creates a case, workflow instance, evidence links, and an internal task.
A case worker can review the application from a guided workflow/case surface.
A workflow step can hand off to appointments/calendar/booking when an appointment is required.
A workflow step can generate a permit or decision document through templates/DMS.
A workflow step can trigger applicant communication through postbox/mail/notifications.
A payment handoff can capture payment evidence and link it to the case/workflow.
Every cross-module action is represented as a capability call, event, DTO, or configuration-package contract, not a direct module import.
Every major step produces audit evidence and user-facing documentation reflects the configured process.

Open Decisions

Whether the first demo should model a generic permit or a concrete example such as a resident parking permit / Anwohnerparkausweis.
Which module owns the applicant-facing status page once a case/workflow exists.
How much permit-specific state belongs in govoplan-permits versus generic cases/workflow/forms.
Which payment path should be mocked first and which should be integrated later.
How configuration packages should express module handoffs, seed data, templates, and rollback.

First Vertical Slice Candidate

A pragmatic first slice:

Simple public permit application form with one uploaded evidence file.
Case creation and workflow start.
One internal review task.
Manual approve/reject transition.
Generated decision document.
Applicant notification.
Audit timeline and configured-process documentation.

Payment and appointment handoff can follow once the basic cross-module chain is proven.

## User Story As a resident or applicant, I want to apply for a permit through a public portal, upload the required evidence, follow the status of my application, attend any required appointment, receive the generated permit or decision, and complete payment where required, so that the whole administrative process is understandable and reliable. As an internal case worker, I want GovOPlaN to create the right case, workflow, tasks, evidence links, appointments, generated documents, communications, payment evidence, and audit trail automatically or semi-automatically, so that I can focus on review and decisions instead of manually coordinating every system step. ## Reference Journey This is the previously documented permit-to-payment story. It is the Wave 1 reference process in `govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md` and is also tracked by `add-ideas/govoplan-core#214` as the configuration-package implementation target. 1. A person applies for a permit through the public portal. 2. Forms runtime receives the submission, validation result, attachments, and submission evidence. 3. Workflow starts a process instance and asks cases to create a durable case record. 4. Files/DMS links uploaded evidence to the case. 5. Tasks assigns intake/review work to the responsible role or function. 6. Workflow moves the case through intake, review, appointment/booking, decision, document generation, communication, payment, and closure. 7. Templates/DMS generates the permit or rejection/decision document. 8. Postbox, mail, and notifications inform the applicant and internal actors. 9. Calendar, appointments, or booking handle appointment handoff where needed. 10. Payments, ledger, and XRechnung record payment and accounting evidence. 11. Audit and records retain the trace of decisions, generated artifacts, communications, and retention state. ## Product Shape The story should become an installable demo/configuration package that wires existing modules into one complete public-administration process. The package should configure the involved forms, case type, workflow definition, task queues, document templates, appointment/payment handoffs, notifications, and user-facing documentation. The operator experience should be guided: users should see where they are in the process, which action is pending, what evidence exists, what the next module handoff will do, and how to return to the process after leaving it. ## Module Touchpoints Likely participating modules: - `module/portal`: public entry point and applicant-facing status surface. - `module/forms`: application form, validation, drafts, submission evidence. - `module/files`: uploaded evidence and generated artifact links. - `module/cases`: durable administrative case record. - `module/workflow`: state machine, handoffs, waits, retries, and progress. - `module/tasks`: internal review and follow-up tasks. - `module/templates`: permit/decision document generation. - `module/permits`: permit/license domain records and lifecycle semantics. - `module/postbox`, `module/mail`, `module/notifications`: applicant and internal communication. - `module/calendar`, `module/appointments`: appointment/booking handoff. - `module/payments`, `module/ledger`, `module/xrechnung`: payment and accounting evidence. - `module/audit`, `module/records`: traceability and retention. ## Acceptance Criteria - A permit-to-payment configuration package can be installed in a local demo environment. - The package creates or references the needed form, case type, workflow definition, task queues, templates, notification rules, and handoff settings. - An applicant can submit a permit application with evidence through the portal/forms path. - The submission creates a case, workflow instance, evidence links, and an internal task. - A case worker can review the application from a guided workflow/case surface. - A workflow step can hand off to appointments/calendar/booking when an appointment is required. - A workflow step can generate a permit or decision document through templates/DMS. - A workflow step can trigger applicant communication through postbox/mail/notifications. - A payment handoff can capture payment evidence and link it to the case/workflow. - Every cross-module action is represented as a capability call, event, DTO, or configuration-package contract, not a direct module import. - Every major step produces audit evidence and user-facing documentation reflects the configured process. ## Open Decisions - Whether the first demo should model a generic permit or a concrete example such as a resident parking permit / `Anwohnerparkausweis`. - Which module owns the applicant-facing status page once a case/workflow exists. - How much permit-specific state belongs in `govoplan-permits` versus generic cases/workflow/forms. - Which payment path should be mocked first and which should be integrated later. - How configuration packages should express module handoffs, seed data, templates, and rollback. ## First Vertical Slice Candidate A pragmatic first slice: 1. Simple public permit application form with one uploaded evidence file. 2. Case creation and workflow start. 3. One internal review task. 4. Manual approve/reject transition. 5. Generated decision document. 6. Applicant notification. 7. Audit timeline and configured-process documentation. Payment and appointment handoff can follow once the basic cross-module chain is proven.

zemion added the