# 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.