pedwfrontend/context/project-overview.md

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.