# PEDW FrontEnd Project Overview

## Purpose

PEDW FrontEnd is a public-service web platform for planning casework and DNS (Developments of National Significance) journeys, with public search and citizen self-service plus authenticated portal/admin capabilities.

## Current Stack

- **Frontend:** Next.js 14 (`pages` router), React 18
- **Server runtime:** Next.js runtime (legacy server files remain in-repo but are not used)
- **State:** Redux + `next-redux-wrapper` + `redux-persist`
- **Auth:** `next-auth` with Prisma adapter and email sign-in flow
- **Auth persistence:** Prisma + SQL Server schema (`prisma/schema.prisma`) for next-auth tables
- **Portal case data source:** Microsoft Dynamics 365 CRM (queried via REST + OData)
- **Portal API transport path:** Frontend API routes -> Azure Service Bus Relay -> Dynamics 365 CRM
- **Relay request integrity:** Forwarded API calls include a hash derived from request path (excluding domain). Relay recomputes hash with shared key and rejects mismatches.
- **i18n:** `next-translate`, locales `en` and `cy`, Welsh rewrites in `next.config.js`
- **Integrations:** Azure storage/queues, GOV.UK Notify, Application Insights, mapping, PDF generation

## Repository Shape (Intent)

- `pages/`: routes and API handlers (`pages/api/**`)
- `components/`: UI and feature components (case, account, admin, mapping, PDF templates)
- `actions/`: API client + shared side-effect logic
- `lib/`: reusable domain helpers and form-related logic
- `store/`: Redux reducers/store hydration/persistence
- `prisma/`: schema and migrations
- `locales/`: translation resources (EN/CY)
- `server/` + root `server.js`: legacy runtime files retained in repository

## Core User/Business Areas

1. Public appeal discovery via:
    - basic search (`/search`)
    - advanced search (`/advancedsearch`)
    - address search (`/addresssearch`)
2. Search results and case summary journey (case reference selection -> summary page)
3. Representation flow from case summary (criteria/date dependent “make representation” action)
4. Passwordless authentication via next-auth magic links for authenticated submissions
5. Authenticated dashboard (`/myportal/**`) for personalised casework
6. New appeal and representation lifecycle management (partial + submitted states)
7. Admin/document workflows

## Planning Casework Portal Dashboard (My Portal)

The Planning Casework dashboard is the authenticated Appellant/Interested party user’s operational home page for:

- starting new appeal submissions
- Viewing the users submitted appeals
- finding existing cases quickly
- resuming in-progress submissions
- monitoring submitted cases/representations
- tracking watched cases
- Information to view infrastructure project activity

The Planning Casework dashboard is the authenticated LPA user’s operational home page for:

- finding existing cases quickly
- resuming in-progress submissions
- monitoring submitted cases/representations
- tracking watched cases
- Information to view infrastructure project activity

The dashboard is organized into task-focused panels that separate **action entry points** (for example, “Make a new appeal”, “Search for a case”) from **state-based worklists** (for example, “Appeals awaiting submission”, “My cases”, and representation lists).

## Public Basic Search Results (Search Journey)

In the public case-discovery journey, the basic search results page provides a structured list of matched cases and key metadata. The page supports sorting and pagination, links each case reference through to case detail, and presents a clear no-results or loading/error state when appropriate.

Results content is locale-aware (EN/CY labels and formatted values) and includes highlighted query matches in key visible fields where supported by returned data.

## User Involvement Model (Portal)

- Newly registered/authenticated portal users default to **Interested Party** involvement.
- Users who raise a new appeal become **Appellants**.
- CRM contact constraints allow only one role type, so once set to Appellant this remains their role.
- **Agents** can submit appeals on behalf of multiple Appellants.
- **LPA (Local Planning Authority)** users have a distinct persona/dashboard view scoped to appeals raised within their authority.
- LPA users do **not** see the “raise appeal” option.
- LPA users can still make/submit representations on appeals.

## Operating Constraints

- Public-sector reliability expectations: avoid regressions on live service paths.
- Bilingual parity is mandatory for user-facing route/content changes.
- Accessibility expectations are high (keyboard and semantic behavior).
- Security-sensitive areas include auth/session, uploads/documents, notifications, and account data.
- Distinguish data paths: next-auth identity/session data is persisted in SQL Server; portal business data is sourced from Dynamics 365 CRM via relay-backed API calls with request-path hash validation.