Merged PR 2433: assessment api grouping
assessment api grouping Related work items: #23754
This commit is contained in:
Robert Bond
@@ -419,6 +419,32 @@ UI journey
|
||||
- legacy endpoint handlers remain canonical
|
||||
- no route migration, deletion, contract change, auth change, storage change, or behaviour change has occurred
|
||||
|
||||
#### Workflow boundary assessment checkpoint
|
||||
|
||||
- A bounded follow-on assessment of the remaining major API families established that the current additive façade pattern has a natural stop point.
|
||||
- Main conclusion:
|
||||
|
||||
> The current façade rollout pattern is proven for bounded read-style journey families, but it should not be stretched across workflow/orchestration-heavy areas without a different design.
|
||||
|
||||
- Classification outcome from the representative family assessment:
|
||||
- **B — Possible façade candidate with caution**
|
||||
- account / registration / personal-details family, but only for a narrowly bounded future read-support slice
|
||||
- **C — Workflow / orchestration boundary**
|
||||
- notifications / email
|
||||
- appeals / drafts / finalisation
|
||||
- representations / drafts / finalisation
|
||||
- **D — Leave unchanged for now**
|
||||
- storage / blob / file operations
|
||||
- auth / session
|
||||
- admin / reporting
|
||||
- What this means for rollout discipline:
|
||||
- the obvious low-risk read-family slices are now largely exhausted
|
||||
- remaining complex areas are complex because they cross identity, storage, queue, Notify, PDF, or finalisation boundaries
|
||||
- those areas do not meet the original checkpoint criteria for the same read-style façade rollout pattern
|
||||
- Recommended next step after the completed façade baseline:
|
||||
- prefer a workflow/orchestration design assessment rather than another broad façade slice
|
||||
- if one more implementation slice is ever chosen first, the only reasonable candidate is a **narrow account read-support cautious slice** that excludes create/update/bootstrap-critical behavior
|
||||
|
||||
---
|
||||
|
||||
### Stage 3 — Documentation Maturity
|
||||
|
||||
@@ -0,0 +1,589 @@
|
||||
# API Grouping Workflow Boundary Assessment
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines where the current **additive read-style façade pattern** naturally stops.
|
||||
|
||||
It is a bounded architecture assessment only.
|
||||
|
||||
It does **not** recommend implementation, migration, route movement, route renaming, route deletion, service URL changes, or behaviour change.
|
||||
|
||||
---
|
||||
|
||||
## Required Context Read
|
||||
|
||||
The following files were read before drafting this assessment:
|
||||
|
||||
- `context/api-grouping-plan.md`
|
||||
- `context/api-grouping-adoption-roadmap.md`
|
||||
- `context/api-route-map.md`
|
||||
- `context/journey-architecture-map.md`
|
||||
- `context/portal-api-platform-assessment.md`
|
||||
- `context/architecture.md`
|
||||
- `memory-bank/change-log.md`
|
||||
|
||||
---
|
||||
|
||||
## Completed Façade Baseline
|
||||
|
||||
Completed additive façade slices now provide a bounded evidence base for what the current pattern does well:
|
||||
|
||||
- **Subscriptions / Watched Cases**
|
||||
- **Documents / Published Document Metadata**
|
||||
- **Public Search Results**
|
||||
- **Case Details Read Journey**
|
||||
- **My Portal Dashboard Reads**
|
||||
|
||||
What these completed slices prove:
|
||||
|
||||
1. The pattern is strongest when the area is **read-only**.
|
||||
2. It works best when a **clear owning service layer** already exists.
|
||||
3. It is lowest risk when a grouped route can **delegate trivially** to a canonical legacy handler.
|
||||
4. It is safest when service adoption can happen **without frontend refactor**.
|
||||
5. It weakens materially once the route family becomes:
|
||||
- identity-coupled
|
||||
- storage-owned
|
||||
- side-effect-heavy
|
||||
- orchestration-heavy
|
||||
- cross-integration by design
|
||||
|
||||
---
|
||||
|
||||
## Classification Model
|
||||
|
||||
### A — Safe façade candidate
|
||||
|
||||
Read-only, clear service layer, low orchestration, stable contract, and additive delegation/adoption would be low risk.
|
||||
|
||||
### B — Possible façade candidate with caution
|
||||
|
||||
Clear journey ownership exists, but the family also touches identity, account state, sensitive reads, or adjacent state assumptions.
|
||||
|
||||
### C — Workflow / orchestration boundary
|
||||
|
||||
Crosses storage, queue, CRM, Notify, PDF generation, finalisation, or other multi-step side effects.
|
||||
|
||||
The current read-style façade pattern should **not** be applied without a separate workflow-specific design.
|
||||
|
||||
### D — Leave unchanged for now
|
||||
|
||||
The area is already reasonably coherent, has unclear adoption value, is integration/platform-owned rather than journey-owned, or does not meet the rollout checkpoint criteria.
|
||||
|
||||
---
|
||||
|
||||
## Family Assessment
|
||||
|
||||
This assessment uses **representative route-family inspection only**.
|
||||
|
||||
It is **not** a full route inventory.
|
||||
|
||||
### 1. Account / Registration / Personal Details
|
||||
|
||||
Representative evidence reviewed:
|
||||
|
||||
- `actions/services/accountDirectService.js`
|
||||
- `pages/api/endpoint/createaccount_api.js`
|
||||
- `pages/api/endpoint/getpersonalaccount_api.js`
|
||||
- `pages/api/endpoint/updateaccount_api.js`
|
||||
- `pages/api/endpoint/getportallogin_api.js`
|
||||
- `pages/api/endpoint/getpreferredlanguage_api.js`
|
||||
|
||||
#### Journey owner
|
||||
|
||||
- account registration
|
||||
- personal details / account management
|
||||
- post-sign-in account bootstrap
|
||||
|
||||
#### Read-only or mutation/orchestration?
|
||||
|
||||
- mixed
|
||||
- includes read-only lookup routes (`getpersonalaccount_api`, `getpreferredlanguage_api`, `getportallogin_api`)
|
||||
- also includes account creation and update mutations (`createaccount_api`, `updateaccount_api`)
|
||||
|
||||
#### Clear service layer?
|
||||
|
||||
- yes
|
||||
- `actions/services/accountDirectService.js`
|
||||
|
||||
#### Integration boundaries crossed?
|
||||
|
||||
- yes
|
||||
- CRM + NextAuth/session bootstrap expectations
|
||||
- signed hash on portal login path
|
||||
|
||||
#### Would façade delegation be trivial?
|
||||
|
||||
- for some reads, yes
|
||||
- for the family as a whole, not safely enough
|
||||
|
||||
#### Would service adoption be safe without frontend refactor?
|
||||
|
||||
- probably for selected reads
|
||||
- not for the whole family without careful identity/bootstrap scoping
|
||||
|
||||
#### Rollout checkpoint fit?
|
||||
|
||||
- only partially
|
||||
- the family fails the clean read-only boundary because account reads are tightly coupled to sign-in/bootstrap and account state
|
||||
|
||||
#### Classification
|
||||
|
||||
- **B — Possible façade candidate with caution**
|
||||
|
||||
#### Assessment conclusion
|
||||
|
||||
Account is the strongest remaining **cautious** candidate, but only as a narrowly bounded future read-support slice.
|
||||
|
||||
The obvious danger is treating identity/bootstrap support routes as if they were ordinary journey reads.
|
||||
|
||||
Any future slice here would need to separate:
|
||||
|
||||
- safe lookup-style reads
|
||||
- from create/update/bootstrap-critical behavior
|
||||
|
||||
---
|
||||
|
||||
### 2. Notifications / Email
|
||||
|
||||
Representative evidence reviewed:
|
||||
|
||||
- `actions/services/notifyDirectService.js`
|
||||
- `pages/api/email/notify.js`
|
||||
- `pages/api/email/getall.js`
|
||||
|
||||
#### Journey owner
|
||||
|
||||
- auth verification email
|
||||
- watchlist/business notifications
|
||||
- completion-triggered communications
|
||||
|
||||
#### Read-only or mutation/orchestration?
|
||||
|
||||
- not read-only
|
||||
- outbound send and aggregation/orchestration focused
|
||||
|
||||
#### Clear service layer?
|
||||
|
||||
- partial
|
||||
- a service exists for direct sends, but route family ownership is broader than one thin service call
|
||||
|
||||
#### Integration boundaries crossed?
|
||||
|
||||
- yes
|
||||
- GOV.UK Notify + CRM + document/event/watchlist aggregation
|
||||
|
||||
#### Would façade delegation be trivial?
|
||||
|
||||
- only for thin `notify.js`
|
||||
- not for the family meaningfully
|
||||
|
||||
#### Would service adoption be safe without frontend refactor?
|
||||
|
||||
- not as a family-level rollout pattern
|
||||
|
||||
#### Rollout checkpoint fit?
|
||||
|
||||
- no
|
||||
- family is orchestration-heavy and cross-cutting
|
||||
|
||||
#### Classification
|
||||
|
||||
- **C — Workflow / orchestration boundary**
|
||||
|
||||
#### Assessment conclusion
|
||||
|
||||
Email is the clearest example of where the read-style façade pattern stops being the right tool.
|
||||
|
||||
Even where one thin send route exists, the family itself is dominated by orchestration and side effects.
|
||||
|
||||
---
|
||||
|
||||
### 3. Appeals / Drafts / Finalisation
|
||||
|
||||
Representative evidence reviewed:
|
||||
|
||||
- `actions/services/documentDirectService.js`
|
||||
- `pages/api/file/createappealcompletemessage_api.js`
|
||||
- `pages/api/endpoint/createcase_api.js`
|
||||
|
||||
#### Journey owner
|
||||
|
||||
- draft appeal creation
|
||||
- save/resume
|
||||
- upload
|
||||
- check answers
|
||||
- finalisation / submission
|
||||
|
||||
#### Read-only or mutation/orchestration?
|
||||
|
||||
- predominantly mutation/orchestration
|
||||
|
||||
#### Clear service layer?
|
||||
|
||||
- multiple services/helpers participate
|
||||
- `documentDirectService`, `caseDirectService`, `accountDirectService`, `azurestorage`
|
||||
|
||||
#### Integration boundaries crossed?
|
||||
|
||||
- yes
|
||||
- Azure Storage + CRM + queue/finalisation + account side effects
|
||||
|
||||
#### Would façade delegation be trivial?
|
||||
|
||||
- not in any useful way for the actual workflow boundary
|
||||
|
||||
#### Would service adoption be safe without frontend refactor?
|
||||
|
||||
- no
|
||||
- service calls are only one part of a broader workflow handoff
|
||||
|
||||
#### Rollout checkpoint fit?
|
||||
|
||||
- no
|
||||
- orchestration-heavy and storage-owned
|
||||
|
||||
#### Classification
|
||||
|
||||
- **C — Workflow / orchestration boundary**
|
||||
|
||||
#### Assessment conclusion
|
||||
|
||||
Appeals are beyond the natural stop point for the current façade pattern.
|
||||
|
||||
If future work is desired here, it needs a **workflow/orchestration-specific design**, not another read-style façade slice.
|
||||
|
||||
---
|
||||
|
||||
### 4. Representations / Drafts / Finalisation
|
||||
|
||||
Representative evidence reviewed:
|
||||
|
||||
- `actions/services/portalDirectService.js`
|
||||
- `pages/api/endpoint/getrepresentations_api.js`
|
||||
- `pages/api/file/createrepcompletemessage_api.js`
|
||||
- `pages/api/file/createrepinvolvement_api.js`
|
||||
|
||||
#### Journey owner
|
||||
|
||||
- public/case representation reads
|
||||
- draft representation editing
|
||||
- representation submission/finalisation
|
||||
|
||||
#### Read-only or mutation/orchestration?
|
||||
|
||||
- mixed, but dominated by workflow concerns once the full journey is considered
|
||||
|
||||
#### Clear service layer?
|
||||
|
||||
- partial
|
||||
- portal/document/notify/storage helpers all participate depending on the journey segment
|
||||
|
||||
#### Integration boundaries crossed?
|
||||
|
||||
- yes
|
||||
- CRM + Azure Storage + queue/finalisation + Notify
|
||||
|
||||
#### Would façade delegation be trivial?
|
||||
|
||||
- only for isolated read endpoints such as `getrepresentations_api`
|
||||
- not for the family as a whole
|
||||
|
||||
#### Would service adoption be safe without frontend refactor?
|
||||
|
||||
- maybe for isolated reads
|
||||
- not for the broader draft/finalisation family
|
||||
|
||||
#### Rollout checkpoint fit?
|
||||
|
||||
- not for the whole family
|
||||
- only limited read-only sub-slices would fit
|
||||
|
||||
#### Classification
|
||||
|
||||
- **C — Workflow / orchestration boundary**
|
||||
|
||||
#### Assessment conclusion
|
||||
|
||||
Representations still contain future read-only candidate edges, but the family requested here is primarily a workflow boundary once drafts, involvement, and completion are included.
|
||||
|
||||
That means the current façade pattern should stop here and not be stretched across the whole area.
|
||||
|
||||
---
|
||||
|
||||
### 5. Storage / Blob / File Operations
|
||||
|
||||
Representative evidence reviewed:
|
||||
|
||||
- `actions/services/documentDirectService.js`
|
||||
- `pages/api/file/uploadsinglefile.js`
|
||||
- `pages/api/file/getprogressobjblob.js`
|
||||
|
||||
#### Journey owner
|
||||
|
||||
- no single journey owner
|
||||
- this is primarily shared integration/platform support for drafts and uploads
|
||||
|
||||
#### Read-only or mutation/orchestration?
|
||||
|
||||
- mixed
|
||||
- read, upload, delete, download, progress, container setup
|
||||
|
||||
#### Clear service layer?
|
||||
|
||||
- yes technically, through `documentDirectService`
|
||||
- but ownership is integration-shaped, not journey-shaped
|
||||
|
||||
#### Integration boundaries crossed?
|
||||
|
||||
- primarily Azure Storage
|
||||
- protected by signed hash/integrity semantics
|
||||
|
||||
#### Would façade delegation be trivial?
|
||||
|
||||
- possible technically
|
||||
- low architectural value for the current grouping goal
|
||||
|
||||
#### Would service adoption be safe without frontend refactor?
|
||||
|
||||
- in some cases, yes
|
||||
- but it would not meaningfully improve journey ownership clarity
|
||||
|
||||
#### Rollout checkpoint fit?
|
||||
|
||||
- no
|
||||
- this family is not a clean journey-owned read family and includes uploads/deletes plus integrity-sensitive support behavior
|
||||
|
||||
#### Classification
|
||||
|
||||
- **D — Leave unchanged for now**
|
||||
|
||||
#### Assessment conclusion
|
||||
|
||||
The storage/file family is exactly the kind of area that should **not** be forced into the same pattern just because wrappers are technically easy.
|
||||
|
||||
It is better treated as an integration-owned support boundary unless a different storage-specific design is approved later.
|
||||
|
||||
---
|
||||
|
||||
### 6. Auth / Session
|
||||
|
||||
Representative evidence reviewed:
|
||||
|
||||
- `pages/api/auth/[...nextauth].js`
|
||||
|
||||
#### Journey owner
|
||||
|
||||
- sign-in
|
||||
- verify request
|
||||
- callback/redirect
|
||||
- locale-aware auth bootstrap
|
||||
|
||||
#### Read-only or mutation/orchestration?
|
||||
|
||||
- orchestration/support
|
||||
|
||||
#### Clear service layer?
|
||||
|
||||
- not in the same sense as the completed façade slices
|
||||
|
||||
#### Integration boundaries crossed?
|
||||
|
||||
- yes
|
||||
- NextAuth + Notify + CRM locale/bootstrap behavior
|
||||
|
||||
#### Would façade delegation be trivial?
|
||||
|
||||
- not usefully
|
||||
|
||||
#### Would service adoption be safe without frontend refactor?
|
||||
|
||||
- not relevant to the current pattern
|
||||
|
||||
#### Rollout checkpoint fit?
|
||||
|
||||
- no
|
||||
- explicitly fails the auth/session-critical guardrail
|
||||
|
||||
#### Classification
|
||||
|
||||
- **D — Leave unchanged for now**
|
||||
|
||||
#### Assessment conclusion
|
||||
|
||||
Auth/session is beyond the current façade rollout boundary.
|
||||
|
||||
This area should remain unchanged unless there is a separate auth-specific design or hardening programme.
|
||||
|
||||
---
|
||||
|
||||
### 7. Admin / Reporting
|
||||
|
||||
Representative evidence reviewed:
|
||||
|
||||
- `actions/services/adminDirectService.js`
|
||||
- `pages/api/admin/getnewappeals_api.js`
|
||||
|
||||
#### Journey owner
|
||||
|
||||
- admin/reporting/internal operational views
|
||||
|
||||
#### Read-only or mutation/orchestration?
|
||||
|
||||
- mostly read-only
|
||||
|
||||
#### Clear service layer?
|
||||
|
||||
- yes
|
||||
- `actions/services/adminDirectService.js`
|
||||
|
||||
#### Integration boundaries crossed?
|
||||
|
||||
- CRM relay only in the reviewed sample
|
||||
|
||||
#### Would façade delegation be trivial?
|
||||
|
||||
- yes technically
|
||||
|
||||
#### Would service adoption be safe without frontend refactor?
|
||||
|
||||
- likely yes
|
||||
|
||||
#### Rollout checkpoint fit?
|
||||
|
||||
- only partially
|
||||
- the main issue is not technical unsuitability but **unclear value**, because `pages/api/admin/*` is already one of the more coherent existing areas
|
||||
|
||||
#### Classification
|
||||
|
||||
- **D — Leave unchanged for now**
|
||||
|
||||
#### Assessment conclusion
|
||||
|
||||
Admin is coherent enough already that another façade layer is not currently justified.
|
||||
|
||||
This is a good example of an area that should stay unchanged unless a concrete maintainer pain justifies more structure.
|
||||
|
||||
---
|
||||
|
||||
## Classification Summary
|
||||
|
||||
| Family | Classification | Why |
|
||||
| ----------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| Account / Registration / Personal Details | **B** | clear service layer, but tightly coupled to identity/bootstrap and includes create/update state changes |
|
||||
| Notifications / Email | **C** | cross-cutting send/orchestration family with Notify + CRM aggregation |
|
||||
| Appeals / Drafts / Finalisation | **C** | storage + CRM + queue + completion side effects |
|
||||
| Representations / Drafts / Finalisation | **C** | contains read edges, but family is dominated by draft/finalisation/orchestration concerns |
|
||||
| Storage / Blob / File Operations | **D** | integration-owned support area, not a clean journey-owned façade target |
|
||||
| Auth / Session | **D** | platform-critical cross-cutting concern; fails current rollout guardrails |
|
||||
| Admin / Reporting | **D** | already coherent enough; unclear value in adding façade grouping now |
|
||||
|
||||
---
|
||||
|
||||
## Façade Continuation Candidates
|
||||
|
||||
Only the following area remains a plausible continuation of the **existing** additive façade pattern:
|
||||
|
||||
### 1. Account read-support slice only, with caution
|
||||
|
||||
Potentially suitable only if narrowly bounded to read-support routes such as:
|
||||
|
||||
- `getpersonalaccount_api.js`
|
||||
- `getpreferredlanguage_api.js`
|
||||
- possibly `getportallogin_api.js` if treated explicitly as bootstrap support rather than generic account read
|
||||
|
||||
Why this is not A:
|
||||
|
||||
- identity/bootstrap coupling is strong
|
||||
- route sensitivity is higher than completed public/myportal/search/case/documents reads
|
||||
- mutations in the same family (`createaccount_api`, `updateaccount_api`) must remain out of scope
|
||||
|
||||
No other remaining family reviewed here is a stronger continuation candidate than this.
|
||||
|
||||
---
|
||||
|
||||
## Workflow / Orchestration Candidates
|
||||
|
||||
These areas need a **different pattern** if future work is ever approved:
|
||||
|
||||
### 1. Notifications / Email
|
||||
|
||||
- thin send routes and aggregation/batch routes should not be treated as one read-style façade family
|
||||
|
||||
### 2. Appeals / Drafts / Finalisation
|
||||
|
||||
- requires workflow-aware design across storage, CRM, queue, and completion sequencing
|
||||
|
||||
### 3. Representations / Drafts / Finalisation
|
||||
|
||||
- requires workflow-aware design across storage, CRM, Notify, and completion/involvement sequencing
|
||||
|
||||
These are the clearest boundaries where the current façade rollout should stop.
|
||||
|
||||
---
|
||||
|
||||
## Leave-Unchanged Areas
|
||||
|
||||
The following areas should remain unchanged for now:
|
||||
|
||||
### 1. Storage / Blob / File Operations
|
||||
|
||||
- integration-owned support boundary
|
||||
- better kept distinct from journey-owned read façades
|
||||
|
||||
### 2. Auth / Session
|
||||
|
||||
- platform-critical and cross-cutting
|
||||
- should not be folded into the current façade rollout model
|
||||
|
||||
### 3. Admin / Reporting
|
||||
|
||||
- already relatively coherent
|
||||
- insufficient evidence that another façade layer would improve maintainability enough to justify it
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
The next step should **not** be another broad façade slice.
|
||||
|
||||
The strongest recommendation is:
|
||||
|
||||
### Prefer a workflow / orchestration design assessment next
|
||||
|
||||
Reason:
|
||||
|
||||
- the completed façade slices have now covered the obvious low-risk read families
|
||||
- the remaining difficult areas are difficult for structural reasons, not because they have not yet been wrapped
|
||||
- stretching the current pattern into workflow-heavy areas would weaken the rollout discipline established by the checkpoint
|
||||
|
||||
### If one more implementation slice is desired before pausing
|
||||
|
||||
The only defensible candidate is:
|
||||
|
||||
- a **narrow account read-support cautious slice**
|
||||
|
||||
and only if it is explicitly bounded to safe read-support routes and excludes create/update/bootstrap-critical behavior.
|
||||
|
||||
### Overall recommendation
|
||||
|
||||
- **Primary recommendation:** workflow/orchestration design pattern assessment
|
||||
- **Secondary fallback:** one cautious account read-support façade slice only
|
||||
- **Do not recommend:** direct continuation into appeals, representations, notifications, auth, or storage families using the current read-style façade pattern
|
||||
|
||||
---
|
||||
|
||||
## Validation Performed
|
||||
|
||||
Documentation-only assessment.
|
||||
|
||||
Performed:
|
||||
|
||||
- read the required context files
|
||||
- direct representative inspection of remaining API families and owning services only
|
||||
- no implementation changes proposed from the evidence itself
|
||||
|
||||
Not performed:
|
||||
|
||||
- no full route inventory
|
||||
- no runtime analysis
|
||||
- no lint/tests required for the assessment itself
|
||||
+472
-415
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user