pedwfrontend/context/api-grouping-workflow-boundary-assessment.md

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