590 lines
16 KiB
Markdown
590 lines
16 KiB
Markdown
# 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
|