pedwfrontend/context/domain-flows.md

Domain Flows Reference

1) Public Search and Case Discovery

Representative routes

• /search, /searchresults, /advancedsearch, /advancedsearchresults, /addresssearch, /addresssearchresults
• /case/[ticketnumber], /dnsapplications, /dnsdetails

Expected behavior

• Users can discover case information without authentication for public data.
• Search and result pagination should remain performant and stable.
• Route aliases in Welsh should mirror English flow intent.
• Search/case data queries route through frontend APIs to Dynamics 365 CRM via Azure Service Bus Relay.
• Relay-bound requests include path-based hash validation (computed client-side and verified relay-side with shared key).
• Case reference selection from results routes the user to a case summary page where representations may be initiated.

1a) Basic search results page (UI behaviour)

• Route is served from the public search flow and presents a dedicated Search results page for a simple keyword/reference query.
• Results heading shows:
  • a result count (@odata.count from CRM response)
  • the searched term in context (for basic search)
  • a linked-case title variant when lk=1 is present.
• Results are displayed as a tabular summary list with columns for:
  • Case reference
  • Site address
  • Applicant
  • Authority (including LPA reference where available)
  • Case type
  • Status
• Case reference links route to case detail (/case/[ticketnumber] or locale/my-portal equivalents), carrying current query context.

1b) Search results interaction model

• Supports column sorting (reference, applicant, authority, case type, status), with ascending/descending state.
• Supports page size selection (5/10/20/30/50) and paginated retrieval.
• While data is loading, page shows a spinner/loading message; CRM error paths render the CRM error component.
• If no matches are returned, page shows a clear no-records state.
• A follow-on CTA links users to advanced search.

1c) Search matching and data presentation

• Basic search can match on case/application references and surfaced metadata (for example authority refs shown in results rows).
• Matching query terms are highlighted in key visible fields where applicable.
• User-facing formatted values (case type/status/authority labels) are locale-aware, with EN/CY translation mapping applied.

Change risks

• Breaking query/filters or pagination contracts.
• Locale rewrite divergence causing EN/CY mismatch.
• Relay or CRM query regressions causing empty/slow/inconsistent results.
• Hash mismatch regressions causing relay rejection of otherwise valid requests.

2) Account and Authentication

Representative routes/APIs

• /auth/signin, /auth/verify-request, /account/register
• pages/api/auth/[...nextauth].js

Expected behavior

• Email sign-in and callback flow should preserve secure redirect behavior.
• Session and account persistence must align with Prisma next-auth models in SQL Server.
• Locale-aware sign-in experience should remain coherent.
• Newly registered/authenticated users are assigned Interested Party involvement by default.

Change risks

• Callback URL mishandling, cross-domain issues, insecure redirects.
• Session expiry/update or cookie behavior regressions.

3) My Portal / Casework Actions

Representative routes

• /myportal, /myportal/viewall, /myportal/case/[ticketnumber]
• new appeal, watched-cases, submissions, and representation workflows

Expected behavior

• Authenticated users manage personal case interactions reliably.
• Redux persistence + hydration should keep client/server state coherent.
• Portal data retrieval should remain stable through relay-backed CRM API queries.
• Dashboard capabilities include:
  • Make a new appeal (guided appeal-type selection)
  • Search for a case by case/application/project reference
  • panel-based worklists for in-progress and submitted user activity

3a) Portal dashboard panel architecture

• The dashboard is a panel grid with two panel types:
  • Action panels: start key actions (new appeal, case search, DNS/project listing).
  • Worklist panels: list records by user relationship and workflow state.
• Worklist panel groups shown in UI include:
  • Appeals awaiting submission
  • My cases
  • Watched cases
  • Representations awaiting submission
  • Submitted representations

3b) Case lifecycle and statuses (portal-visible)

• From dashboard behavior, case/representation records appear in practical states:
  • Awaiting submission (draft/incomplete, resumable)
  • Pending (submitted and active in processing)
  • Submission processing (recently submitted representation still being processed)
• The UI separates these states into distinct panels rather than one combined status list.

3c) Domain entities used in dashboard flows

• Case: core planning case record identified by case reference (for example CAS-...).
• Appeal: a casework submission type associated with an appeal type and LPA.
• Representation: a statement/consultation response linked to a case.
• LPA: Local Planning Authority associated with the case/appeal and shown as context metadata.

3d) User-to-case relationships

• Owner / My case: user is the primary submitting party (“My cases” panel).
• Watcher: user follows case updates without being the owning submitter (“Watched cases” panel).
• Representative / On behalf of: user acts for another party in case/appeal activity (shown as “On behalf of” in case cards).
• Related role constraints remain:
  • users become Appellants when they raise a new appeal
  • CRM contact constraints allow only one role type, so Appellant remains their role once assigned
  • Agents can submit appeals on behalf of multiple Appellants
  • LPA users receive a different dashboard view focused on appeals in their local authority
  • LPA users do not have the raise-appeal action in dashboard UI
  • LPA users can raise/submit representations on appeals

Change risks

• HYDRATE/persist regressions causing stale or missing state.
• Unauthorized access gaps in protected paths.

4) New Appeal and Representation Submission

Representative areas

• pages/newappeal/**, components/newappeal/**
• representation flows in components/case/representation/**

Expected behavior

• Form progression, save/continue, and submission paths are resilient.
• Generated PDFs/documents and notifications are consistent with submitted data.
• “Make representation” availability on case summary is criteria/date dependent.
• Users can begin representation flow from summary, but must be authenticated to submit.

4a) Representation submission workflow (dashboard view)

1. User finds/selects a case (search or existing case list).
2. User starts a representation (for example statement/consultation response).
3. Incomplete work appears in Representations awaiting submission.
4. On submit, status may briefly show Submission processing.
5. Completed items move to Submitted representations.

4b) Case search behaviour (portal dashboard)

• Search accepts multiple reference types from one input:
  • case reference
  • infrastructure project reference
  • LPA application reference
• UI guidance shows accepted patterns similar to:
  • APP-A12345-A-21-1234567
  • CAS-12345-A1B2C3
• Search panel provides direct links to Address search and Advanced Search for broader discovery routes.

Change risks

• Data mapping/validation drift; malformed uploads or document payloads.
• Missing notifications or incorrect template/locale usage.

5) Document, Upload, and Notification Processing

Representative APIs

• pages/api/file/**
• pages/api/email/**

Expected behavior

• File handling respects allowed types/size and error paths.
• Email/notification side effects are reliable and observable.

Change risks

• Unsafe file handling, leakage of sensitive details in logs, or queue failures.

Cross-Flow Non-Functional Expectations

• Accessibility: keyboard/focus/labels/semantic headings for UI changes.
• Bilingual parity: EN/CY text/routes maintained together.
• Public-service reliability: avoid user-visible regressions in key journeys.