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.