# 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