995 lines
22 KiB
Markdown
995 lines
22 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|