docs(governance): track context docs and add relay rollout controls
This commit is contained in:
@@ -0,0 +1,112 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user