# 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

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