Merged PR 2413: updated docs

updated docs Related work items: #23754
2026-06-22 05:36:30 +00:00
parent 0150e243ed
commit 27fceffbc9
7 changed files with 15851 additions and 132 deletions
@@ -33,18 +33,13 @@ CRMURL = "ts-pedw.crm11.dynamics.com"
 CRMURL_VERSION = "v9.2"

 # //New PreProd  
-# CLIENT_ID = ab6c4678-b31a-4eb3-b429-e039120e488a
-# CLIENT_SECRET = VWY8Q~9EtRzGXpd8Xs~5OS1fej2IyVJ8JgTMncw3
-# RELAY_ROOT = https://ar-ns-lz-pedw-ppe-uks-01.servicebus.windows.net/ar-hc-lz-pedw-ppe-uks-01/  
-# RELAYURI = "ar-ns-lz-pedw-ppe-uks-01.servicebus.windows.net"
-# RELAYPATH = "ar-hc-lz-pedw-ppe-uks-01"
-# # RELAY_ROOT = https://ar-ns-lz-pedw-ppe-ukw-01.servicebus.windows.net/ar-hc-lz-pedw-ppe-ukw-01/  
-# # RELAYURI = "ar-ns-lz-pedw-ppe-ukw-01.servicebus.windows.net"
-# # RELAYPATH = "ar-hc-lz-pedw-ppe-ukw-01"
-# # CRMURL = "ppcrm2016.llcdt.gov.wales/PPPINSWales"
-# # CRMURL_VERSION = "v8.2"
-# CRMURL = "wg-pp-pedw.crm11.dynamics.com"
-# CRMURL_VERSION = "v9.2"
+CLIENT_ID = ab6c4678-b31a-4eb3-b429-e039120e488a
+CLIENT_SECRET = VWY8Q~9EtRzGXpd8Xs~5OS1fej2IyVJ8JgTMncw3
+RELAY_ROOT = https://ar-ns-lz-pedw-ppe-uks-01.servicebus.windows.net/ar-hc-lz-pedw-ppe-uks-01/  
+RELAYURI = "ar-ns-lz-pedw-ppe-uks-01.servicebus.windows.net"
+RELAYPATH = "ar-hc-lz-pedw-ppe-uks-01"
+CRMURL = "wg-pp-pedw.crm11.dynamics.com"
+CRMURL_VERSION = "v9.2"


 # //Prod Oauth WGO
@@ -61,61 +56,11 @@ CRMURL_VERSION = "v9.2"
 # RELAY_ROOT = https://ar-ns-lz-pedw-prod-uks-01.servicebus.windows.net/ar-hc-lz-pedw-prod-uks-01/  
 # RELAYURI = "ar-ns-lz-pedw-prod-uks-01.servicebus.windows.net"
 # RELAYPATH = "ar-hc-lz-pedw-prod-uks-01"
-# # RELAY_ROOT = https://ar-ns-lz-pedw-ppe-ukw-01.servicebus.windows.net/ar-hc-lz-pedw-prod-ukw-01/  
-# # RELAYURI = "ar-ns-lz-pedw-prod-ukw-01.servicebus.windows.net"
-# # RELAYPATH = "ar-hc-lz-pedw-prod-ukw-01"
 # CRMURL = "crm2016.llc.gov.wales/PEDW"
 # CRMURL_VERSION = "v8.2"



-# D365 cnr WGO
-# CLIENT_ID = 3125ac03-91ac-46a7-a166-0086f0ed90b3
-# CLIENT_SECRET = bFq8Q~9VX5Ra3lKnGGIXsB.G6-ZGMx7LqyqXjdr4
-# RELAY_ROOT = https://ar-ns-lz-pedw-d365cnr-uks-01.servicebus.windows.net/ar-hc-lz-pedw-d365cnr-uks-01/ 
-# RELAYURI = "ar-ns-lz-pedw-d365cnr-uks-01.servicebus.windows.net"
-# RELAYPATH = "ar-hc-lz-pedw-d365cnr-uks-01"
-# CRMURL = "dv-pedw.crm11.dynamics.com"
-# CRMURL_VERSION = "v9.2"
-
-# D365 Dev WGO
-# CLIENT_ID = 9b834097-03d7-409b-b038-ecfec31a394a
-# CLIENT_SECRET = .Jf8Q~tKMObCJjhh_hy3J5AIctFrBalU4FS~tdxk
-# RELAY_ROOT = https://ar-ns-lz-pedw-d365dev-uks-01.servicebus.windows.net/ar-hc-lz-pedw-d365dev-uks-01/ 
-# RELAYURI = "ar-ns-lz-pedw-d365dev-uks-01.servicebus.windows.net"
-# RELAYPATH = "ar-hc-lz-pedw-d365dev-uks-01"
-# CRMURL = "dv-pedw.crm11.dynamics.com"
-# CRMURL_VERSION = "v9.2"
-
-# D365 Test WGO
-# CLIENT_ID = d40b9373-96c2-4b04-8bd8-c2a2fe6444c1
-# CLIENT_SECRET = 6hT8Q~glL~jloWpGmvXw3UY37QFwjUE0r._jobEM
-# RELAY_ROOT = https://ar-ns-lz-pedw-d365test-uks-01.servicebus.windows.net/ar-hc-lz-pedw-d365test-uks-01/ 
-# RELAYURI = "ar-ns-lz-pedw-d365test-uks-01.servicebus.windows.net"
-# RELAYPATH = "ar-hc-lz-pedw-d365test-uks-01"
-# CRMURL = "ts-pedw.crm11.dynamics.com"
-# CRMURL_VERSION = "v9.2"
-
-# D365 PP WGO
-# CLIENT_ID = ab6c4678-b31a-4eb3-b429-e039120e488a
-# CLIENT_SECRET = V288Q~P1lFMvvX9Xnkx2pLixK~GOREH983Owqc1E
-# RELAY_ROOT = https://ar-ns-lz-pedw-d365ppe-uks-01.servicebus.windows.net/ar-hc-lz-pedw-d365ppe-uks-01/ 
-# RELAYURI = "ar-ns-lz-pedw-d365ppe-uks-01.servicebus.windows.net"
-# RELAYPATH = "ar-hc-lz-pedw-d365ppe-uks-01"
-# CRMURL = "wg-pp-pedw.crm11.dynamics.com"
-# CRMURL_VERSION = "v9.2"
-
-# D365 Prod WGO
-# CLIENT_ID = 3e4141a3-1fbd-454e-98f0-7f3a4f14a3cc
-# CLIENT_SECRET = ULC8Q~fZiXm0.teVLlZ_7LjxBOj2vIsWSApu2bAq
-# RELAY_ROOT = https://ar-ns-lz-pedw-d365prod-uks-01.servicebus.windows.net/ar-hc-lz-pedw-d365prod-uks-01/ 
-# RELAYURI = "ar-ns-lz-pedw-d365prod-uks-01.servicebus.windows.net"
-# RELAYPATH = "ar-hc-lz-pedw-d365prod-uks-01"
-# CRMURL = "wg-prod-pedw.crm11.dynamics.com"
-# CRMURL_VERSION = "v9.2"
-
-
-//GOOGLE_TAG_MANAGER = GTM-T78CBC3
 GOOGLE_TAG_MANAGER = G-GTWW3JT03Z

 SHOWLOGIN = true
@@ -135,38 +80,24 @@ NEXTAUTH_URL = $API_ROOT
 NEXTAUTH_URL_INTERNAL = $API_ROOT
 NEXTAUTH_SECRET = SuperSecret

-// CNR sql server 
+# CNR sql server 
 # DATABASE_URL = sqlserver://sql-srv-plt-pedw-cnr-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword

-// dev test sql server 
+# dev test sql server 
 DATABASE_URL = sqlserver://sql-srv-plt-pedw-dev-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword

-// test sql server 
+# test sql server 
 DATABASE_URL = sqlserver://sql-srv-plt-pedw-test-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword

-// Pre prod sql server
-# DATABASE_URL = sqlserver://sql-srv-plt-pedw-ppe-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustservercertificate=true;hostnameincertificate=*.database.windows.net;logintimeout=30;authentication=SqlPassword
+# Pre prod sql server
+DATABASE_URL = sqlserver://sql-srv-plt-pedw-ppe-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustservercertificate=true;hostnameincertificate=*.database.windows.net;logintimeout=30;authentication=SqlPassword

-// Prod sql server
+# Prod sql server
 # DATABASE_URL = sqlserver://pp-pedw-sql.database.windows.net:1433;database=PEDWPreProd;user=RobBondSQL;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword

-// Prod sql server
+# Prod sql server
 # DATABASE_URL = sqlserver://sql-srv-plt-pedw-prod-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword

-// D365 CNR sql server 
-# DATABASE_URL = sqlserver://sql-srv-plt-pedw-d365cnr-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword
-  
-// D365 Dev sql server 
-# DATABASE_URL = sqlserver://sql-srv-plt-pedw-d365dev-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword
-  
-// D365 Test sql server 
-# DATABASE_URL = sqlserver://sql-srv-plt-pedw-d365test-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword
-
-// D365 PPE sql server 
-# DATABASE_URL = sqlserver://sql-srv-plt-pedw-d365ppe-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword
-
-// D365 Prod sql server 
-# DATABASE_URL = sqlserver://sql-srv-plt-pedw-d365prod-uks-01.database.windows.net:1433;database=PEDW;user=PedwSqlAdmin;password=GhWKr62F5sQ69dZx;encrypt=true;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;authentication=ActiveDirectoryPassword



@@ -174,31 +105,31 @@ SECRET = SuperSecret



-//Azure Storage Account
+# Azure Storage Account
 AZURE_CLIENT_ID	= $CLIENT_ID
 AZURE_TENANT_ID	= $TENANT
 AZURE_CLIENT_SECRET = $CLIENT_SECRET

-// CNR key
+# CNR key
 AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwcnruks"
 AZURE_STORAGE_ACCOUNT_KEY = hRffHq4IwctpaTKdS/U33Xq6nyTDF1t++WJgIwsw7gzstktZin/rRwbTIAL9KKqesVsK7EHrTTG6+ASt4+7skw==
 AZURE_PEDW_STORAGE_ENDPOINT = https://sapltpedwcnruks.blob.core.windows.net

-// new dev key
+# new dev key
 AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwdevuks"
 AZURE_STORAGE_ACCOUNT_KEY = MmrsrCjBfop9pI2oImsP/+lJUWU2DrXsAB8nq5bOVROTmPovSGxjCjKw9+TAFr00k8WDUK9r6mVx+AStcMLyAA==
 AZURE_PEDW_STORAGE_ENDPOINT = https://sapltpedwdevuks.blob.core.windows.net

-// New test key
+# New test key
 AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwtestuks"
 # AZURE_STORAGE_ACCOUNT_KEY = 5NdDO9GGlbTFLHFOXZRw8H2C0Ow5bFTvHwUHEbStyzg2mbd1uwHSeBSvM/dkN+HfdwrFzqAkwL5P+AStdO6cig==
 AZURE_STORAGE_ACCOUNT_KEY = bqJAz5pYQVGee8dnVhlsqW+xHwinNTjgY2AmojNyB+d4uAotMR20WcO4Op13yB+9dFaXAkkjtIA4+AStHT/IYg==
 AZURE_PEDW_STORAGE_ENDPOINT = https://sapltpedwtestuks.blob.core.windows.net

-// New preprod key
-# AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwppeuks"
-# AZURE_STORAGE_ACCOUNT_KEY = B4GRKr+cA9b9mNM/GHFivzhzflJIZltG8bMmooXlYvGYySPAspTTHistAT30sHipnR+hh6dqUc9q+ASttAjPRQ==
-# AZURE_PEDW_STORAGE_ENDPOINT = https://sapltpedwppeuks.blob.core.windows.net
+# New preprod key
+AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwppeuks"
+AZURE_STORAGE_ACCOUNT_KEY = B4GRKr+cA9b9mNM/GHFivzhzflJIZltG8bMmooXlYvGYySPAspTTHistAT30sHipnR+hh6dqUc9q+ASttAjPRQ==
+AZURE_PEDW_STORAGE_ENDPOINT = https://sapltpedwppeuks.blob.core.windows.net


 # PROD key
@@ -211,58 +142,32 @@ AZURE_PEDW_STORAGE_ENDPOINT = https://sapltpedwtestuks.blob.core.windows.net
 # AZURE_STORAGE_ACCOUNT_KEY = OfV9MFqXcLLPam9GhEdMWadIOwIzhc5hd5TUqzIuQoswFdtV4ybaemjatSv+Kht0Ny1qQKjLplwY+AStUTZJrg==
 # AZURE_PEDW_STORAGE_ENDPOINT =  https://sapltpedwproduks.blob.core.windows.net

-# D365 CNR key
-# AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwd365cnruks"
-# AZURE_STORAGE_ACCOUNT_KEY = nEwCp+4FuVf/9a4DOyKuQO2yRRV4Ypigg20ch1YaiL09YmEhWMEO5pNLpYtI3WnQCkIqeu1CUqwM+AStCLW01g==
-# AZURE_PEDW_STORAGE_ENDPOINT =  https://sapltpedwd365cnruks.blob.core.windows.net
-
-# D365 DEV key
-# AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwd365devuks"
-# AZURE_STORAGE_ACCOUNT_KEY = XzwQxuZXSwYrVgemDUD2ymTpYTIfWqhypbmEALw1ZEEP0M4D3b3Gh28clSymxwFu7Gu9mhwkW4/V+AStZ6RF8Q==
-# AZURE_PEDW_STORAGE_ENDPOINT =  https://sapltpedwd365devuks.blob.core.windows.net
-
-# D365 TEST key
-# AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwd365testuks"
-# AZURE_STORAGE_ACCOUNT_KEY = 5NdDO9GGlbTFLHFOXZRw8H2C0Ow5bFTvHwUHEbStyzg2mbd1uwHSeBSvM/dkN+HfdwrFzqAkwL5P+AStdO6cig==
-# AZURE_PEDW_STORAGE_ENDPOINT =  https://sapltpedwd365testuks.blob.core.windows.net
-
-# D365 PP key
-# AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwd365ppeuks"
-# AZURE_STORAGE_ACCOUNT_KEY = xQz4FWDnQDE09uPOCj1t7axRiquvZG9vbxL88ywzVsJnTsAgewrHnuAGkxGPBCp2xGE53ffYOme6+AStSr8OoQ==
-# AZURE_PEDW_STORAGE_ENDPOINT =  https://sapltpedwd365ppeuks.blob.core.windows.net
-
-# D365 Prod key
-# AZURE_STORAGE_ACCOUNT_NAME = "sapltpedwd365produks"
-# AZURE_STORAGE_ACCOUNT_KEY = DvKcWhDpFKMFdVXFF2SqDG0sYQ3AkNCmJUBG0cvgzi5NBHS4Ahd2hPAlfA3hGi2EbohUag3vCucK+ASt1IdBhA==
-# AZURE_PEDW_STORAGE_ENDPOINT =  https://sapltpedwd365produks.blob.core.windows.net
-

 AZURE_PEDW_CONTAINER = "pedwapplications"
 AZURE_PEDW_QUEUE_ENDPOINT = https://$AZURE_STORAGE_ACCOUNT_NAME.queue.core.windows.net

-//gov.notify
-//NOTIFY_API_KEY = pedwnextauthkey-90f93710-9dae-423e-aea1-11eccd0dc132-0c9469d9-d671-444d-9e9d-3e5a62001043
-NOTIFY_API_KEY = pedwnextauthlivekey-90f93710-9dae-423e-aea1-11eccd0dc132-5c0ed187-754a-4b04-8c99-978e5710c2c1
+# gov.notify
+# NOTIFY_API_KEY = pedwnextauthkey-90f93710-9dae-423e-aea1-11eccd0dc132-0c9469d9-d671-444d-9e9d-3e5a62001043
+# NOTIFY_API_KEY = pedwnextauthlivekey-90f93710-9dae-423e-aea1-11eccd0dc132-5c0ed187-754a-4b04-8c99-978e5710c2c1
+NOTIFY_API_KEY = pedwnextauthlive01key-90f93710-9dae-423e-aea1-11eccd0dc132-72bfb1e1-c0b7-47cb-9887-3d47a4b11ad4
 
 SHOW_DEBUG = true

 
-// DEV Connection string
+# DEV Connection string
 NEXT_PUBLIC_APP_INSIGHT = InstrumentationKey=4b7568b3-70bd-4591-9dc2-267c0a6501d1;IngestionEndpoint=https://ukwest-0.in.applicationinsights.azure.com/;LiveEndpoint=https://ukwest.livediagnostics.monitor.azure.com/;ApplicationId=447d38b5-5d40-4238-8fb3-0ef4741b3db1
 
-
 APPLICATIONINSIGHTS_CONNECTIONSTRING = InstrumentationKey=7a06e24a-793c-47bc-8987-ce80f180e035;IngestionEndpoint=https://uksouth-1.in.applicationinsights.azure.com/;LiveEndpoint=https://uksouth.livediagnostics.monitor.azure.com/;ApplicationId=9906b6d0-b791-4add-8d53-c827a534e1d4

-
-// Test Connection string
+# Test Connection string
 NEXT_PUBLIC_APP_INSIGHT = InstrumentationKey=cc60e8e7-5b30-4c2b-a176-8b96b21b12df;IngestionEndpoint=https://ukwest-0.in.applicationinsights.azure.com/;LiveEndpoint=https://ukwest.livediagnostics.monitor.azure.com/;ApplicationId=2a4094be-6fd1-46ab-a67d-5f241692b129
 
-// Preprod Connection string
+# Preprod Connection string
 # NEXT_PUBLIC_APP_INSIGHT = InstrumentationKey=7370f0f9-834d-4c7a-b3c4-9951fcad5ad2;IngestionEndpoint=https://ukwest-0.in.applicationinsights.azure.com/;LiveEndpoint=https://ukwest.livediagnostics.monitor.azure.com/;ApplicationId=04362cb7-6dfc-469e-8274-12243e8be851

 # NEXT_PUBLIC_APP_INSIGHT = InstrumentationKey=a41b91bf-f7dc-4f44-bb66-a67df4eee435;IngestionEndpoint=https://uksouth-1.in.applicationinsights.azure.com/;LiveEndpoint=https://uksouth.livediagnostics.monitor.azure.com/;ApplicationId=473d0632-16f1-4065-8984-d6bac62402c0
 
-// Prod Connection string
+# Prod Connection string
 # NEXT_PUBLIC_APP_INSIGHT = InstrumentationKey=61f358c2-8075-4164-b897-17bc6dd31fee;IngestionEndpoint=https://ukwest-0.in.applicationinsights.azure.com/;LiveEndpoint=https://ukwest.livediagnostics.monitor.azure.com/;ApplicationId=0c297349-396b-4dc6-8b56-85f5c680adc6


@@ -273,4 +178,6 @@ SHOWSIPS = true
 ALLOWED_IPS=::1,203.0.113.42,198.51.100.17
 UPLOAD_BATCH_COUNT = 5

-NRWDOMAIN = rdbmedia.co.uk
+NRWDOMAIN = rdbmedia.co.uk
+
+MAP_TARGET = pedw-dev
@@ -0,0 +1,994 @@
+# 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.
@@ -18,15 +18,287 @@ Adoption Planning

 ### Next Recommended Architecture Stream

-Portal API Security & Access Boundary Assessment
+Authorization architecture stream complete.
+
+Next recommended architecture stream:
+
+Portal authorization hardening / consistency planning (documentation-first, implementation only by explicit approval)

 ### Objectives

- endpoint inventory
- authenticated/public classification
- ownership validation review
- access-control consistency review
- security boundary assessment
+- record completed assessment conclusions
+- preserve stable authorization architecture model
+- use the model as a baseline for future hardening/change review
+
+## Portal API Platform Assessment Status (2026-06-20)
+
+### Stream status
+
+**Portal Integration Contract & API Platform Assessment: COMPLETE**
+
+### Consolidated architectural conclusion
+
+The PEDW API platform is large in route count but materially smaller in underlying structure than the file count first suggests.
+
+At an architecture level it is best understood as:
+
+```text
+Large route surface
+    ↓
+small route-family vocabulary
+    ↓
+small contract-shape vocabulary
+    ↓
+small implementation-style vocabulary
+```
+
+The main architectural and maintenance issue is therefore not discovery of a fundamentally different API architecture.
+
+It is primarily:
+
+- findability
+- ownership clarity
+- consistency and reuse discipline
+
+### Stable route-family model
+
+The completed assessment supports the following stable API platform families:
+
+- CRM relay routes
+- storage/blob routes
+- finalisation/orchestration routes
+- email/notification routes
+- document download routes
+- auth/session routes
+- admin/internal routes
+- middleware/helper routes
+- local utility/meta routes
+
+### Stable contract-shape model
+
+The completed assessment supports the following repeated contract shapes:
+
+- Public CRM read
+- User-owned CRM read
+- CRM create
+- CRM update/patch
+- CRM delete
+- Proxy/pass-through
+- Lookup/config/support
+- Hybrid upsert/orchestration
+- Storage read/write/delete
+- Queue/finalisation
+- Notify send / notification orchestration
+
+### Stable implementation-style model
+
+Three main implementation styles explain most of the API surface:
+
+1. **Newer helper-oriented**
+    - `relayGet(...)`
+    - `relayGetData(...)`
+    - `respondSuccess(...)`
+    - `respondError(...)`
+    - relay policy presets
+2. **Older direct-wrapper**
+    - `getToken()`
+    - direct `axios(config)`
+    - manual `WEBAPI_URL + queryUrl + hashAPIPath(queryUrl)`
+3. **Orchestration-heavy**
+    - finalisation routes
+    - email aggregation routes
+    - storage + queue + CRM side-effect routes
+
+These older patterns are not inherently incorrect; they reflect prior delivery constraints. The key future discipline is whether they should be copied forward when shared helper patterns already exist.
+
+### Folder drift and maintenance hotspots
+
+Stable drift model:
+
+- low drift: `documents`, `admin`, `middleware`, top-level utility/meta
+- low/moderate drift: `auth`
+- moderate drift: `email`
+- high drift: `endpoint`, `file`
+
+Highest maintenance hotspots:
+
+- **high:** `pages/api/endpoint`, `pages/api/file`
+- **medium-high:** `pages/api/auth`, `pages/api/middleware`
+- **medium:** `pages/api/email`
+- **lower:** `pages/api/documents`, `pages/api/admin`
+
+### Proven / not proven status
+
+#### Proven
+
+- the API platform assessment is representative at the pattern level
+- route count overstates true structural diversity
+- most routes are explained by a small number of repeated route families, contract shapes, and implementation styles
+- the main maintenance problem is findability and ownership clarity
+
+#### Not proven
+
+- no full route-by-route inventory was produced
+- no route consolidation safety assessment has been performed
+- no implementation readiness decision has been approved
+- no route movement or removal is recommended at this stage
+
+### Programme guidance
+
+This stream should now be considered complete.
+
+If future work is approved, it should be framed as:
+
+- API Route Map / Maintainer Guide planning
+- API rationalisation planning
+
+and not as implementation work by default.
+
+## Portal Authorization Architecture Status (2026-06-19)
+
+### Stream status
+
+**Portal API Security & Access Boundary Assessment: COMPLETE**
+
+### Consolidated architectural conclusion
+
+PEDW currently exhibits a **distributed authorization model**.
+
+The dominant observed pattern is:
+
+```text
+Identity established
+    ↓
+Ownership scope established
+    ↓
+Ownership identifier propagated
+    ↓
+Integrity controls applied
+    ↓
+Operation executed
+```
+
+rather than a uniformly route-local model where identity and ownership are re-derived and re-proven inside each final handler.
+
+### Principal authorization roots
+
+#### Public anonymous
+
+```text
+Anonymous
+→ public search
+→ public case viewing
+```
+
+#### CRM-owned data
+
+```text
+NextAuth session
+→ session.user.email
+→ getPortalLogin(email)
+→ CRM Contact
+→ CRM relationships
+→ CRM operations
+```
+
+#### Draft / storage-owned data
+
+```text
+NextAuth session
+→ session.user.id
+→ user-specific storage container
+→ draft JSON
+→ uploaded files
+```
+
+### Integrity and execution controls
+
+#### Signed hash
+
+The signed hash most clearly provides:
+
+- route integrity
+- query integrity
+- parameter integrity
+- identifier integrity
+
+It should be understood as:
+
+> an integrity control rather than an object-authorization control.
+
+#### Azure Storage execution
+
+```text
+PEDW API
+→ Azure SDK
+→ storage account credentials
+→ Azure Storage
+```
+
+Users do not directly access Azure Storage in the reviewed architecture.
+
+#### Azure Relay execution
+
+```text
+PEDW API
+→ signed hash
+→ Azure Relay
+→ CRM
+```
+
+Relay hash validation is a route/path integrity mechanism.
+
+Relay-to-CRM authentication remains out of scope for this architecture conclusion.
+
+### Proven / not proven status
+
+#### Proven
+
+- distributed authorization model exists
+- ownership is generally established upstream
+- identifiers are propagated downstream
+- route-local referential verification is not consistently visible
+- storage ownership is rooted in `session.user.id`
+- CRM ownership is rooted in CRM Contact identity
+- signed hash strengthens integrity controls
+- storage execution is server-mediated rather than direct browser-to-storage
+
+#### Not proven
+
+- no confirmed exploitability
+- no demonstrated User A → User B mutation
+- no demonstrated authorization bypass
+- no evidence that prior OWASP assessments, health checks, or penetration tests are invalid
+- no evidence of direct browser-to-storage or direct browser-to-CRM access
+
+### Risk characterization
+
+The completed stream should be understood primarily as:
+
+- architectural integrity risk
+- auditability risk
+- maintainability risk
+- future-change risk
+
+It should **not** currently be characterised as:
+
+- a confirmed vulnerability
+- a demonstrated exploit
+- broken authorization
+
+unless materially new evidence emerges.
+
+### Programme guidance
+
+No immediate remediation programme is recommended on current evidence alone.
+
+If future work is approved, it should be framed as:
+
+- authorization hardening
+- consistency improvements
+- maintainability improvements
+
+rather than emergency security remediation.

 ## Runtime Topology