pedwfrontend/context/api-route-map.md

API Route Map & Maintainer Guide

Status

First-generation maintainer guide.

This document follows the completed:

• Domain Architecture Programme
• Authorization Architecture Assessment
• Portal Integration Contract & API Platform Assessment

It is maintainability-focused.

It is not a full route inventory.

Purpose

This route map is intended to help a maintainer answer four practical questions before changing API behaviour:

Where should I start?
Which APIs are involved?
Which helpers are involved?
What integrations and risks am I touching?

The key working assumption from the completed assessment is:

Routes are primarily owned by journeys/features, not folders.

---

Journey Catalogue

1. Public Search

Purpose

Supports public case search, filtering, pagination, and result shaping across standard and advanced search journeys.

Primary UI Entry Points

• pages/searchresults.js
• pages/advancedsearchresults.js
• components/search/searchresults.js
• components/search/addresssearchresults.js
• components/search/dnssearchresults.js

Service Layer

• actions/services/searchDirectService.js
  • getBasicSearchPaged
  • getAdvancedSearchPaged
  • related basic/advanced search helpers

API Routes

• pages/api/endpoint/getbasicsearch_api.js
• pages/api/endpoint/getbasicsearchpaged_api.js
• pages/api/endpoint/getadvancedsearch_api.js
• pages/api/endpoint/getadvancedsearchpaged_api.js
• adjacent variants:
  • getbasicsearch_by_address_api.js
  • getbasicsearch_by_lparref_api.js
  • DNS/public search variants

Integrations

• CRM Relay
• Local-only

Ownership Type

• feature-owned

Change Risk

• high

Reason:

• public-facing
• contract-critical results and filters
• paged/unpaged variants
• transform-heavy output shaping

First-Look Checklist

Before changing public search:

1. Inspect the relevant getbasicsearch* / getadvancedsearch* route family
2. Inspect searchDirectService callers
3. Confirm paging, sorting, and transform expectations
4. Check whether related document/detail routes are also affected

---

2. Case Details

Purpose

Supports public and portal case detail retrieval, linked-case lookups, messages, and related case-view data.

Primary UI Entry Points

• pages/case/[ticketnumber].js
• pages/case/id/[incident].js
• components/case/summary.js
• components/case.js

Service Layer

• actions/services/caseDirectService.js
  • getCase
  • getCaseByID
  • getCaseMessage
  • getIncidentbyID

API Routes

• pages/api/endpoint/getcase_api.js
• pages/api/endpoint/getcasebyid_api.js
• pages/api/endpoint/getincidentbyid_api.js
• pages/api/endpoint/getcasemessage_api.js
• pages/api/endpoint/getlinkedcases_api.js

Integrations

• CRM Relay

Ownership Type

• feature-owned

Change Risk

• high

Reason:

• case detail contracts are widely consumed
• related routes often share assumptions about identifiers and transformed fields

First-Look Checklist

Before changing case details:

1. Inspect the relevant case detail route family
2. Inspect caseDirectService callers
3. Check linked-case/message side routes
4. Confirm UI expectations in case summary/detail components

---

3. Documents

Purpose

Supports published document metadata retrieval and published document download.

Primary UI Entry Points

• components/search/searchresults.js
• case/search document links surfaced in search and case journeys

Service Layer

• actions/services/searchDirectService.js
• actions/services/caseDirectService.js for adjacent case-document lookups

API Routes

• pages/api/endpoint/getsearchdocumentdetails_api.js
• pages/api/endpoint/getsearchdocumentdetailspaged_api.js
• pages/api/endpoint/getsearchdocumenthistory_api.js
• pages/api/endpoint/getsearchdocumenthistorypaged_api.js
• pages/api/endpoint/getsearchdocumentTypes_api.js
• pages/api/documents/download/[id].js

Integrations

• CRM Relay
• Local-only

Ownership Type

• feature-owned with an integration-owned download proxy boundary

Change Risk

• high

Reason:

• direct user-facing download behaviour
• metadata, hash-link generation, and binary delivery split across multiple areas

First-Look Checklist

Before changing documents:

1. Inspect metadata/detail/history routes
2. Inspect documents/download/[id].js
3. Confirm hash-link generation expectations
4. Check search/case UI consumers that surface document links

---

4. My Portal Dashboard

Purpose

Supports authenticated portal lists and dashboard cards for cases, representations, and awaiting-submission work.

Primary UI Entry Points

• pages/myportal/index.js
• components/myportal/topthree.js
• components/myportal/viewall.js
• components/myportal.js

Service Layer

• actions/services/portalDirectService.js
• actions/services/documentDirectService.js for draft/blob-backed dashboard items

API Routes

• pages/api/endpoint/getmycases_api.js
• pages/api/endpoint/getmyrepresentations_api.js
• pages/api/endpoint/getawaitingsubmission_api.js
• adjacent blob/proxy routes for draft-backed data

Integrations

• CRM Relay
• Azure Storage

Ownership Type

• feature-owned

Change Risk

• high

Reason:

• authenticated portal-critical journey
• mixes CRM-owned and draft/blob-backed data

First-Look Checklist

Before changing my portal dashboard:

1. Inspect primary dashboard list routes
2. Inspect portalDirectService and documentDirectService
3. Check dashboard components (topthree, viewall)
4. Check portal state modules and current-view assumptions

---

5. Watched Cases

Purpose

Supports create/read/delete behaviour for watched cases across search, case, and myportal journeys.

Primary UI Entry Points

• components/search/searchresults.js
• components/case/summary.js
• components/myportal/topthree.js
• components/myportal/viewall.js

Service Layer

• actions/services/portalDirectService.js
  • getWatchedCases
  • getWatchedCasesProxy
  • createWatchedCases
  • deleteWatchedCases

API Routes

• pages/api/endpoint/getwatchedcases_api.js
• pages/api/endpoint/getwatchedcasesproxy_api.js
• pages/api/endpoint/createwatchedcases_api.js
• pages/api/endpoint/deletewatchedcases_api.js
• pages/api/endpoint/deletewatchedcasesproxy_api.js

Integrations

• CRM Relay
• Local-only

Ownership Type

• feature-owned with orchestration on create/upsert

Change Risk

• high

Reason:

• multiple entry points
• state refresh after mutation
• mixed proxy/non-proxy and upsert behaviour

First-Look Checklist

Before changing watched cases:

1. Inspect watched case route family
2. Inspect portalDirectService
3. Inspect store/watchedCases/* and store/currentView/*
4. Inspect CRM relationship and duplicate-check assumptions

---

6. Representations

Purpose

Supports representation retrieval, editing, and related case/portal representation views.

Primary UI Entry Points

• pages/myportal/representation.js
• components/representation.js
• components/case/representation/*

Service Layer

• actions/services/portalDirectService.js
• actions/services/documentDirectService.js

API Routes

• pages/api/endpoint/getrepresentations_api.js
• pages/api/endpoint/getrepresentationsproxy_api.js
• pages/api/endpoint/getmyrepresentations_api.js
• pages/api/endpoint/getmyrepresentationsproxy_api.js
• adjacent representation draft/blob routes in pages/api/file

Integrations

• CRM Relay
• Azure Storage

Ownership Type

• feature-owned

Change Risk

• high

Reason:

• representation journeys span CRM records and blob-backed draft/edit data

First-Look Checklist

Before changing representations:

1. Inspect representation read routes
2. Inspect blob-backed draft/edit support routes
3. Inspect portal/document service callers
4. Inspect currentView and related representation state

---

7. Draft Appeals

Purpose

Supports draft appeal progress, draft files, and storage-backed resume state before submission.

Primary UI Entry Points

• pages/newappeal/[appealtypes].js
• pages/myportal/[appealtypes].js
• lib/newappeal/loadNewAppealPage.js
• lib/myportal/loadMyPortalAppealPage.js

Service Layer

• actions/services/documentDirectService.js
• actions/azurestorage.js

API Routes

• pages/api/file/getprogressobjblob.js
• pages/api/file/getbloblist.js
• pages/api/file/upload.js
• pages/api/file/uploadsinglefile.js
• pages/api/file/deleteblobcase.js
• pages/api/file/setupcontainer.js

Integrations

• Azure Storage
• Local-only

Ownership Type

• integration-owned supporting a feature journey

Change Risk

• high

Reason:

• storage-backed draft integrity
• upload/delete/progress flows are user-critical before submission

First-Look Checklist

Before changing draft appeals:

1. Inspect progress/blob list/upload/delete routes
2. Inspect documentDirectService
3. Inspect actions/azurestorage.js
4. Inspect new appeal loaders and draft state assumptions

---

8. Draft Representations

Purpose

Supports representation draft JSON/files before final representation submission.

Primary UI Entry Points

• pages/myportal/representation.js
• components/case/representation/*
• lib/representation/pageLoaders.js

Service Layer

• actions/services/documentDirectService.js
• actions/azurestorage.js

API Routes

• pages/api/file/getrepsblob.js
• pages/api/file/getrepsblobproxy.js
• pages/api/file/editRepJson.js
• pages/api/file/upload.js
• pages/api/file/deleteblobrep.js

Integrations

• Azure Storage

Ownership Type

• integration-owned supporting a feature journey

Change Risk

• high

Reason:

• draft representation data and uploads are part of a sensitive user submission path

First-Look Checklist

Before changing draft representations:

1. Inspect rep blob routes and edit JSON route
2. Inspect documentDirectService
3. Inspect storage helper behaviour in actions/azurestorage.js
4. Check representation page loader and currentView dependencies

---

9. Appeal Submission / Finalisation

Purpose

Transitions draft appeal state into submitted/finalised processing.

Primary UI Entry Points

• pages/myportal/[appealtypes].js
• lib/myportal/loadMyPortalAppealPage.js
• new appeal completion and check-answer flows

Service Layer

• actions/services/documentDirectService.js
• actions/services/accountDirectService.js
• actions/services/caseDirectService.js
• actions/azurestorage.js

API Routes

• pages/api/file/createappealcompletemessage_api.js
• pages/api/file/createappealcompletemessageproxy_api.js
• pages/api/endpoint/createcase_api.js
• pages/api/endpoint/patchcase_api.js
• pages/api/endpoint/updatecase_api.js

Integrations

• CRM Relay
• Azure Storage
• Azure Queue
• Local-only

Ownership Type

• orchestration-owned

Change Risk

• very high

Reason:

• crosses storage, queue/finalisation, and CRM write boundaries
• contract-critical workflow transition

First-Look Checklist

Before changing appeal submission/finalisation:

1. Inspect completion/finalisation routes
2. Inspect createcase_api, patchcase_api, updatecase_api
3. Inspect documentDirectService and azurestorage helpers
4. Inspect draft loaders and state handoff assumptions

---

10. Representation Submission / Finalisation

Purpose

Transitions drafted or newly entered representation content into submitted representation processing.

Primary UI Entry Points

• pages/myportal/representation.js
• components/case/representation/representationComplete.js

Service Layer

• actions/services/portalDirectService.js
• actions/services/documentDirectService.js
• actions/services/notifyDirectService.js
• actions/azurestorage.js

API Routes

• pages/api/file/createrepcompletemessage_api.js
• pages/api/file/createrepinvolvement_api.js
• pages/api/endpoint/deletemyrepresentations_api.js
• adjacent representation read/write support routes in endpoint and file

Integrations

• CRM Relay
• Azure Storage
• Azure Queue
• GOV.UK Notify

Ownership Type

• orchestration-owned

Change Risk

• very high

Reason:

• multi-integration workflow
• user submission and notification side effects

First-Look Checklist

Before changing representation submission/finalisation:

1. Inspect completion and involvement routes
2. Inspect representation completion component and callers
3. Inspect portal/document/notify service helpers
4. Confirm storage, CRM, and notification sequencing assumptions

---

11. Account Registration

Purpose

Creates CRM-backed portal account/contact records for authenticated users who do not yet have portal account state.

Primary UI Entry Points

• pages/account/register.js
• components/account/registerform.js
• components/account/registerCheck.js
• components/account/registerComplete.js

Service Layer

• actions/services/accountDirectService.js
  • createAccount
  • getPortalLogin

API Routes

• pages/api/endpoint/createaccount_api.js
• pages/api/endpoint/getemailaccountcheck_api.js
• pages/api/endpoint/getportallogin_api.js

Integrations

• CRM Relay
• NextAuth

Ownership Type

• feature-owned

Change Risk

• high

Reason:

• identity bootstrap and portal account creation are foundational

First-Look Checklist

Before changing account registration:

1. Inspect create-account and login/account-check routes
2. Inspect accountDirectService
3. Inspect registration pages/components
4. Confirm session-to-contact bootstrap assumptions

---

12. Personal Details / Account Management

Purpose

Supports personal details retrieval and update for authenticated portal users.

Primary UI Entry Points

• pages/account/personaldetails.js
• components/account/personaldetails.js
• components/myportal/youraccount.js

Service Layer

• actions/services/accountDirectService.js
  • getPersonalAccount
  • updateAccount

API Routes

• pages/api/endpoint/getpersonalaccount_api.js
• pages/api/endpoint/updateaccount_api.js
• adjacent support routes:
  • getpreferredlanguage_api.js
  • updatepassword_api.js

Integrations

• CRM Relay
• NextAuth
• Local-only

Ownership Type

• feature-owned

Change Risk

• high

Reason:

• user-critical account data
• identity/bootstrap coupling

First-Look Checklist

Before changing personal details/account management:

1. Inspect account read/update routes
2. Inspect accountDirectService
3. Inspect account pages/components
4. Inspect accountDetails state and session/bootstrap dependencies

---

13. Authentication / Sign-In

Purpose

Handles sign-in, verify-request, callback, redirect, and locale-aware auth/session behaviour.

Primary UI Entry Points

• pages/index.js
• auth pages and callback entry paths

Service Layer

• lib/auth/*
• actions/services/accountDirectService.js for portal login resolution

API Routes

• pages/api/auth/[...nextauth].js
• pages/api/auth/resolve-locale.js
• adjacent support routes:
  • pages/api/endpoint/getportallogin_api.js
  • pages/api/endpoint/getpreferredlanguage_api.js

Integrations

• NextAuth
• GOV.UK Notify
• CRM Relay

Ownership Type

• support-owned with platform-critical behavior

Change Risk

• very high

Reason:

• session and redirect behaviour are highly sensitive
• cross-cutting impact across the platform

First-Look Checklist

Before changing authentication/sign-in:

1. Inspect [...nextauth].js
2. Inspect locale resolution behavior
3. Inspect portal login/preferred-language supporting routes
4. Confirm callback, redirect, and EN/CY assumptions

---

14. Notifications / Email

Purpose

Handles direct Notify sends and broader notification workflows that gather CRM/document/event data before sending.

Primary UI Entry Points

• journey completion flows
• auth verify-request/sign-in flows
• background or triggered notification flows

Service Layer

• actions/services/notifyDirectService.js
• actions/services/portalDirectService.js

API Routes

• pages/api/email/notify.js
• pages/api/email/getall.js
• pages/api/email/getdocuments.js
• pages/api/email/getevents.js
• pages/api/email/getmailinglist.js
• pages/api/email/getcaseref.js

Integrations

• GOV.UK Notify
• CRM Relay
• Local-only

Ownership Type

• orchestration-owned

Change Risk

• high

Reason:

• user communications
• template and timing side effects
• some routes aggregate data before sending

First-Look Checklist

Before changing notifications/email:

1. Inspect whether the route is a thin send route or an aggregation route
2. Inspect Notify helper usage
3. Inspect document/event/list side data dependencies
4. Confirm EN/CY template assumptions

---

15. Admin / Reporting

Purpose

Provides internal/admin reporting and grouped status/document views.

Primary UI Entry Points

• admin pages/components
• internal reporting views

Service Layer

• actions/services/adminDirectService.js

API Routes

• pages/api/admin/getnewappeals_api.js
• pages/api/admin/getlatestdocuments_api.js
• pages/api/admin/getStatusCountsByAppealAndLPA_api.js
• adjacent status/reporting routes in admin

Integrations

• CRM Relay

Ownership Type

• support-owned

Change Risk

• medium

Reason:

• smaller, more coherent area
• still CRM-transform heavy and potentially used operationally

First-Look Checklist

Before changing admin/reporting:

1. Inspect the relevant admin route family
2. Inspect adminDirectService
3. Confirm reporting/grouping transform assumptions
4. Check whether public or portal-facing contracts are indirectly reused

---

Shared Platform Section

Shared API Building Blocks

relayGet(...)

• Responsibility: standardized CRM relay GET forwarding
• Commonly used in: pages/api/endpoint/**, especially read families
• Preferred for future work? yes, for new CRM read routes where the shared relay-read model fits

relayGetData(...)

• Responsibility: supplementary relay-backed data fetches inside transforms/orchestration
• Commonly used in: advanced search enrichment, lookup hybrids, upsert pre-checks
• Preferred for future work? yes, where a route needs sub-queries without directly writing to res

respondSuccess(...)

• Responsibility: shared success JSON response envelope
• Commonly used in: endpoint, file, email, admin, and middleware-aware routes
• Preferred for future work? yes

respondError(...)

• Responsibility: shared error JSON response envelope
• Commonly used in: endpoint, file, email, admin, and middleware-aware routes
• Preferred for future work? yes

Relay policy helpers / presets

• Responsibility: shared timeout/retry profiles for relay reads
• Commonly used in: modern helper-oriented relay routes
• Preferred for future work? yes, where an existing policy profile is appropriate

Hash helpers

• Responsibility: path signing and request-integrity validation
• Commonly used in: relay-bound routes and storage/blob routes
• Preferred for future work? yes, where the existing signed-route model must be preserved

Signed request helpers

• Responsibility: shared signed GET/POST/DELETE request execution
• Commonly used in: service/client layer helpers for signed route access
• Preferred for future work? yes, where signed request composition already exists

Azure storage helpers

• Responsibility: blob/container/queue operations and related metadata handling
• Commonly used in: pages/api/file/**, draft/finalisation helpers, storage-backed journeys
• Preferred for future work? yes for storage-facing behavior

Notify helpers

• Responsibility: GOV.UK Notify send behavior and related helper flows
• Commonly used in: pages/api/email/**, auth email flow, service layer
• Preferred for future work? yes, but keep send routes thin unless orchestration is required

Auth/session helpers

• Responsibility: session establishment, locale resolution, auth-related supporting context
• Commonly used in: pages/api/auth/**, SSR loaders, auth support flows
• Preferred for future work? yes within the established NextAuth/session boundary

---

Maintainer Guidance

When Adding a New API

Recommended decision sequence:

1. Which journey owns this?
2. Which integration does it touch?
3. Does an existing route family already exist?
4. Can existing helpers be reused?
5. Is the route contract-critical?

Guidance notes:

• start from journey ownership before folder ownership
• prefer existing families and helpers where they already fit
• do not copy older direct-wrapper patterns by default when newer shared patterns exist
• do not refactor stable legacy routes without explicit approval and characterization

---

Risks / Cautions

1. This is a first-generation maintainer guide, not a full inventory.
2. It is intentionally journey-first and route-family-first, not exhaustive route-by-route documentation.
3. Folder names still do not reliably indicate current ownership.
4. High-risk changes still need direct file inspection before editing, especially in endpoint, file, auth, and finalisation flows.

---

Validation performed

Manual consolidation only.

Performed:

• re-read required assessment and architecture context
• reused the stable findings from the completed API platform assessment
• converted folder-oriented conclusions into a journey-owned maintainer route map

Not performed:

• no new runtime analysis
• no scripts
• no automated inventory generation
• no code changes

---

Recommendation

This route map is sufficient as a first-generation maintainer guide.

An additional documentation slice is justified only if the team wants one of the following future planning outputs:

• a more detailed API Route Map / Maintainer Guide v2 with deeper per-journey edge cases
• an API Rationalisation Planning document focused on future consolidation candidates

No implementation work is recommended from this guide alone.