Engineer Onboarding Guide — PEDW FrontEnd

1) Project Overview

PEDW FrontEnd is the Planning and Environment Decisions Wales (PEDW) portal for discovering planning appeals and accessing personalised casework journeys. It supports public search/browse and authenticated dashboard workflows, with strong accessibility and bilingual (English/Welsh) requirements.

2) Technology Stack

Frontend: Next.js 14 (Pages Router), React 18
Language: Primarily JavaScript (some TypeScript tooling present)
State: Redux, next-redux-wrapper, redux-persist, redux-thunk, redux-form
Auth: next-auth + Prisma adapter (email magic-link flow)
Auth data layer: Prisma + SQL Server (prisma/schema.prisma) for next-auth identity/session tables
Portal business data layer: Dynamics 365 CRM queried via REST + OData through frontend API routes
i18n: next-translate + i18n.js + Welsh rewrites in next.config.js
Integrations: Azure Service Bus Relay (CRM transport), Azure Blob/Queue, GOV.UK Notify, Application Insights, mapping (Leaflet/google-map-react), PDF generation

3) Architecture Overview

Active runtime is Next.js runtime (legacy custom server files exist but are inactive).
UI routes and APIs live in pages/ and pages/api/**.
Security controls are applied through middleware.js + security headers in next.config.js.
Auth/session logic is centralized in pages/api/auth/[...nextauth].js.
Shared integration/service logic sits mostly in actions/ (notably large actions/index.js).
Portal data calls are sent from pages/api/endpoint/** to Dynamics 365 CRM through Azure Service Bus Relay.
For relay-bound calls, a hash is generated from request path (excluding domain) and appended; relay validates using the same shared hash key.

4) Repository Structure

pages/ — routes + API handlers
components/ — UI/features (case, DNS, account, admin, mapping, PDF templates)
actions/ — API client and side-effect helpers
lib/ — reusable form/domain helpers
store/ — Redux reducers/store setup/hydration/persistence
prisma/ — schema + migrations
locales/ — EN/CY translations
data/ — lookup and form metadata files
tests/ — test area (appears limited)
server/, server.js — legacy/inactive runtime artifacts

5) Core System Components

Public search/case flows: basic search (/search), advanced search (/advancedsearch), and address search (/addresssearch) with result pages and case detail/document UIs
Account/auth: next-auth email verification and Prisma-backed sessions
Portal routes (/myportal/**): user-specific case/representation/watchlist workflows
File/doc pipeline: upload/download/blob flows and PDF generation under pages/api/file/**
Notifications: GOV.UK Notify integrations under pages/api/email/** + auth email provider

5a) User Involvement / Role Model

Newly registered/authenticated users default to Interested Party involvement.
Users who raise a new appeal become Appellants.
CRM contact constraints allow only one role type; once Appellant is assigned, it remains their role.
Agents can submit appeals on behalf of multiple Appellants.
LPA (Local Planning Authority) users are a separate persona with a distinct dashboard view.
LPA dashboards focus on appeals within that authority.
LPA users cannot raise appeals (option is hidden), but they can submit representations.

6) Data Model

Prisma schema is focused on next-auth persistence (SQL Server):

User
Account
Session
VerificationToken

Datasource is SQL Server (DATABASE_URL). This model underpins authentication/session behavior and should be treated as sensitive core infrastructure. Portal business/case data is sourced separately from Dynamics 365 CRM via relay-backed API calls.

7) Key Workflows

Sign-in: user requests magic link -> email via Notify -> callback/session via next-auth.
Search journey: frontend query -> pages/api/endpoint/** proxy endpoint(s) -> path hash appended -> Azure Service Bus Relay (validates hash with shared key) -> Dynamics 365 CRM (REST/OData) -> normalized UI rendering.
Case summary to representation: user selects case reference from results -> lands on case summary -> “make representation” shown only when criteria/date rules allow -> user can start flow but must be authenticated to submit.
Dashboard journey (/myportal): signed-in users can raise new appeals, search appeals, view watched cases, view partially completed appeals, view submitted appeals, and manage submitted/partially submitted representations.
Role behavior: default involvement starts as Interested Party; new appeal creation sets Appellant role (persistent due to CRM single-role contact model); Agent users may act for multiple Appellants.
LPA dashboard behavior: LPA users see an authority-scoped dashboard, do not see raise-appeal options, and can raise representations on existing appeals.
Document workflow: user upload/submit -> blob storage + metadata updates -> PDF/document retrieval.
Bilingual routing: Welsh aliases rewired in next.config.js, locale resources in locales/en|cy, page namespace mapping in i18n.js.

8) Development Workflow

From scripts and runbook:

npm run dev — local dev
npm run build + npm start — production build/start
npm run lint — baseline validation

Expected change protocol emphasizes:

scoped changes,
EN/CY parity checks,
accessibility smoke checks,
negative-path checks on sensitive flows,
memory-bank/log updates for non-trivial changes.

9) Observed Conventions

4-space indentation, no trailing commas (per local conventions)
Keep page-level logic thin where possible; place reusable logic in lib//components//actions/
API naming pattern commonly uses *_api.js
Heavy use of proxy-style API handlers
Existing AI governance artifacts define guardrails (.clinerules, GUARDRAILS.md, context/, memory-bank/)

10) Potential Risks / Weak Areas

Large actions/index.js coupling (many responsibilities in one module)
API contract inconsistency (error/response handling varies across endpoints)
Extensive console.log footprint (signal/noise and potential sensitive logging concerns)
Duplication across API proxy handlers (token/header/hash/relay logic repeated)
i18n complexity drift risk (rewrite + locale namespace parity maintenance)
Limited automated tests for high-risk flows (manual validation burden)

6.5 KiB Raw Blame History