pedwfrontend/context/api-grouping-plan.md

API Grouping Plan

Status

Planning only.

Pilot status update (2026-06-25):

• first additive grouping façade pilot implemented for watched-case APIs under pages/api/subscriptions/
• legacy watched-case endpoint routes under pages/api/endpoint/ remain canonical and stable
• no route removal, migration, contract change, or behaviour change has occurred
• the pilot validates the journey-owned grouping model through additive façade wrappers only

This document defines a future journey-owned API grouping model for PEDW using the completed architecture programme as its evidence base.

It does not recommend implementation, migration, route movement, route renaming, file movement, contract change, or behaviour change.

---

Required Context Read

The following files were read before drafting this plan:

• context/api-route-map.md
• context/journey-architecture-map.md
• context/portal-api-platform-assessment.md
• context/architecture.md
• context/integration-map.md
• memory-bank/change-log.md

---

Files Modified

• context/api-grouping-plan.md
• memory-bank/change-log.md

---

Findings

• The completed architecture programme already established that PEDW has a large route surface but a smaller underlying architectural vocabulary.
• The main API maintenance problem is not missing discovery. It is primarily:
  • findability
  • ownership clarity
  • consistency
  • reuse discipline
• Existing top-level folders do not consistently express current business ownership.
• The strongest current drift remains in:
  • pages/api/endpoint
  • pages/api/file
• The most stable architecture-level API families are already known and should be treated as established:
  • 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
• The journey and route maps already support a journey-owned view of the platform. This plan therefore synthesises those findings into a maintainability-focused future grouping model only.

---

Proposed API Grouping Model

Future grouping concepts for documentation guidance only:

pages/api/

    account/
    admin/
    appeals/
    auth/
    cases/
    documents/
    notifications/
    platform/
    representations/
    search/
    subscriptions/
    shared/

Interpretation guidance:

• These are architectural grouping concepts only.
• They describe future journey ownership, not approved folder structure.
• They do not imply that current routes should move.
• They do not imply that route count should reduce.
• They do not imply that contracts, integrations, or behaviour should change.

---

Group Definitions

1. account/

Purpose

Owns authenticated user account creation, account bootstrap, personal details retrieval, and account maintenance behavior.

Primary Journeys Supported

• account registration
• personal details
• account maintenance
• post-sign-in account bootstrap

Typical Integrations

• CRM
• NextAuth

Typical Route Types

• read
• create
• update
• lookup

Example Existing Routes

• pages/api/endpoint/createaccount_api.js
• pages/api/endpoint/getpersonalaccount_api.js
• pages/api/endpoint/updateaccount_api.js
• pages/api/endpoint/getemailaccountcheck_api.js

Shared Components Used

• relay helpers
• response helpers
• auth/session helpers
• signed request helpers

Relationship To Other Groups

• depends on auth/ for identity establishment
• supports appeals/, representations/, and subscriptions/ where CRM contact identity is required
• relies on shared/ and platform/ helper layers

Migration Cautions

• Future grouping candidate only.
• Account routes remain tightly coupled to session bootstrap and CRM contact identity.
• Documentation guidance only; any future grouping would need to preserve current session-to-contact resolution and all existing contracts.

---

2. admin/

Purpose

Owns internal reporting, operational summaries, and admin-facing grouped data views.

Primary Journeys Supported

• admin reporting
• operational status views
• internal appeal/document summaries

Typical Integrations

• CRM

Typical Route Types

• read
• lookup
• aggregation

Example Existing Routes

• pages/api/admin/getnewappeals_api.js
• pages/api/admin/getlatestdocuments_api.js
• pages/api/admin/getStatusCountsByAppealAndLPA_api.js

Shared Components Used

• relay helpers
• response helpers
• logging helpers

Relationship To Other Groups

• depends on shared CRM relay/platform helpers
• generally adjacent to cases/, appeals/, and documents/ data rather than owning those journeys

Migration Cautions

• Leave current admin routes effectively unchanged for now at the architecture level.
• This is already one of the more coherent current families.
• Documentation guidance only.

---

3. appeals/

Purpose

Owns draft appeal progression, appeal submission/finalisation, and appeal-specific workflow orchestration.

Primary Journeys Supported

• start appeal
• save and exit
• resume appeal
• upload supporting files for appeal draft
• check answers
• submit appeal
• appeal completion

Typical Integrations

• CRM
• Azure Storage
• Azure Queue
• NextAuth

Typical Route Types

• read
• create
• update
• upload
• delete
• orchestration

Example Existing Routes

• pages/api/file/getprogressobjblob.js
• pages/api/file/getbloblist.js
• pages/api/file/createappealcompletemessage_api.js
• pages/api/endpoint/createcase_api.js
• pages/api/endpoint/patchcase_api.js

Shared Components Used

• Azure SDK helpers
• hash helpers
• relay helpers
• response helpers
• auth/session helpers

Relationship To Other Groups

• depends on account/ for authenticated contact context
• depends on platform/ / shared/ for storage, queue, relay, validation, and response support
• intersects with documents/ for user-facing file handling patterns

Migration Cautions

• Future grouping candidate only.
• Appeal flows cross storage-owned draft state and CRM-owned submitted state.
• Any future grouping would need to preserve sequencing, payload shapes, queue handoff, and contract-critical finalisation behavior.

---

4. auth/

Purpose

Owns session establishment, sign-in callbacks, locale-aware auth routing, and auth-support bootstrap behavior.

Primary Journeys Supported

• sign in
• verify request
• callback/redirect handling
• locale-aware auth bootstrap

Typical Integrations

• NextAuth
• GOV.UK Notify
• CRM

Typical Route Types

• orchestration
• lookup
• support

Example Existing Routes

• pages/api/auth/[...nextauth].js
• pages/api/auth/resolve-locale.js
• adjacent support routes such as pages/api/endpoint/getpreferredlanguage_api.js

Shared Components Used

• auth/session helpers
• Notify helpers
• response helpers
• logging helpers

Relationship To Other Groups

• foundational cross-cutting dependency for account/, appeals/, representations/, and subscriptions/
• shares responsibility boundaries with notifications/ where auth emails are sent

Migration Cautions

• Cross-cutting concern; not a simple journey folder.
• Future grouping candidate only.
• Any future grouping would need to preserve current callback, redirect, locale, verification-email, and session behavior exactly.

---

5. cases/

Purpose

Owns case-detail retrieval, case messages, linked-case reads, and case-adjacent read models used by public and portal journeys.

Primary Journeys Supported

• public case details
• linked case viewing
• case messages/notices
• case-adjacent portal detail lookups

Typical Integrations

• CRM

Typical Route Types

• read
• lookup
• aggregation

Example Existing Routes

• pages/api/endpoint/getcase_api.js
• pages/api/endpoint/getcasebyid_api.js
• pages/api/endpoint/getcasemessage_api.js
• pages/api/endpoint/getlinkedcases_api.js
• pages/api/endpoint/getportalmoduledetails_api.js

Shared Components Used

• relay helpers
• response helpers
• signed request helpers

Relationship To Other Groups

• closely related to search/ because public case detail often begins through search-family reads
• supports subscriptions/ and representations/ journeys that need case context
• relies on shared CRM/platform helpers

Migration Cautions

• Future grouping candidate only.
• Current case-detail retrieval is partly search-shaped rather than purely case-by-route shaped.
• Documentation guidance only; any future grouping would need to preserve current identifier assumptions and case-detail payload contracts.

---

6. documents/

Purpose

Owns published document metadata retrieval and published document delivery/download behavior.

Primary Journeys Supported

• published document discovery
• published document download
• document history/detail retrieval

Typical Integrations

• CRM
• Azure Relay

Typical Route Types

• read
• lookup
• download

Example Existing Routes

• pages/api/endpoint/getsearchdocumentdetails_api.js
• pages/api/endpoint/getsearchdocumenthistory_api.js
• pages/api/endpoint/getsearchdocumentTypes_api.js
• pages/api/documents/download/[id].js

Shared Components Used

• relay helpers
• hash helpers
• response helpers
• signed request helpers

Relationship To Other Groups

• closely related to search/ and cases/ because those journeys surface published document links
• distinct from appeal/representation draft storage APIs

Migration Cautions

• Natural future grouping candidate for published-document behavior.
• Keep published-document discovery separate from draft-storage document handling in any future planning.
• Documentation guidance only.

---

7. notifications/

Purpose

Owns outbound notification sending and orchestration routes that gather business data before sending transactional communications.

Primary Journeys Supported

• sign-in verification email
• completion notifications
• watchlist-related notifications
• business-triggered outbound email

Typical Integrations

• GOV.UK Notify
• CRM

Typical Route Types

• create
• orchestration
• lookup
• aggregation

Example Existing Routes

• pages/api/email/notify.js
• pages/api/email/getall.js
• pages/api/email/getdocuments.js
• pages/api/email/getevents.js

Shared Components Used

• Notify helpers
• relay helpers
• response helpers
• logging helpers

Relationship To Other Groups

• intersects with auth/ for verification/sign-in email behavior
• intersects with subscriptions/, appeals/, and representations/ for journey-triggered notifications

Migration Cautions

• Cross-cutting concern rather than a single business journey.
• Notification routes vary from thin send helpers to broader orchestration routes.
• Documentation guidance only; no implementation recommendation.

---

8. platform/

Purpose

Owns platform-level support routes and utility/meta endpoints that are not naturally journey-owned business APIs.

Primary Journeys Supported

• platform health/support
• utility/meta API behaviors
• route-level support concerns

Typical Integrations

• local-only
• CRM lookup support where applicable

Typical Route Types

• support
• lookup
• meta
• health

Example Existing Routes

• pages/api/health.js
• pages/api/doc.ts
• pages/api/notices/index.js

Shared Components Used

• response helpers
• logging helpers
• validation helpers

Relationship To Other Groups

• supports all journey groups indirectly
• distinct from shared/, which is a component/helper classification rather than an API-journey group

Migration Cautions

• Likely leave unchanged for now at the API-family level unless a future planning slice establishes clearer journey ownership.
• Documentation guidance only.

---

9. representations/

Purpose

Owns representation retrieval, draft representation lifecycle, and representation submission/finalisation orchestration.

Primary Journeys Supported

• start representation
• select capacity / representation type
• enter content
• upload supporting files
• save and resume representation draft
• check answers
• submit representation
• representation completion

Typical Integrations

• CRM
• Azure Storage
• Azure Queue
• GOV.UK Notify
• NextAuth

Typical Route Types

• read
• create
• update
• upload
• delete
• orchestration

Example Existing Routes

• pages/api/file/getrepsblob.js
• pages/api/file/editRepJson.js
• pages/api/file/createrepcompletemessage_api.js
• pages/api/file/createrepinvolvement_api.js
• pages/api/endpoint/getrepresentations_api.js

Shared Components Used

• Azure SDK helpers
• hash helpers
• relay helpers
• Notify helpers
• response helpers
• auth/session helpers

Relationship To Other Groups

• depends on cases/ for case context
• depends on account/ and auth/ for identity/bootstrap
• intersects with notifications/ for representation communications
• depends on platform/ / shared/ helpers for storage, queue, relay, and validation

Migration Cautions

• Future grouping candidate only.
• Representation routes span both read models and orchestration-heavy submission side effects.
• Any future grouping would need to preserve storage ownership, CRM representation relationships, and completion sequencing.

---

10. search/

Purpose

Owns public search, advanced search, search-detail expansion, and public discovery-oriented lookups.

Primary Journeys Supported

• basic search
• advanced search
• result paging and sorting
• search-to-case navigation bootstrap

Typical Integrations

• CRM

Typical Route Types

• read
• lookup
• aggregation

Example Existing 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
• pages/api/endpoint/getbasicsearchdetails_api.js

Shared Components Used

• relay helpers
• response helpers
• relay policy helpers
• signed request helpers

Relationship To Other Groups

• upstream journey dependency for cases/ and documents/
• relies on shared CRM/platform helpers

Migration Cautions

• Natural future grouping candidate.
• Preserve public search contracts, paging assumptions, and detail-expansion behavior.
• Documentation guidance only.

---

11. subscriptions/

Purpose

Owns watched-case and unsubscribe-related behavior, including subscription-like user relationships to cases and related notification preferences.

Primary Journeys Supported

• watch case
• unwatch case
• view watched cases
• unsubscribe / unsubscribe-all flows

Typical Integrations

• CRM
• GOV.UK Notify

Typical Route Types

• read
• create
• delete
• update
• orchestration

Example Existing Routes

• pages/api/endpoint/getwatchedcases_api.js
• pages/api/endpoint/createwatchedcases_api.js
• pages/api/endpoint/deletewatchedcases_api.js
• pages/api/endpoint/deletewatchedcasesproxy_api.js

Shared Components Used

• relay helpers
• relayGetData helpers
• response helpers
• auth/session helpers

Relationship To Other Groups

• depends on account/ and auth/ for identity context
• supports cases/, search/, and my portal style journeys
• intersects with notifications/ because watchlist state participates in notification behavior

Migration Cautions

• Future grouping candidate only.
• Some notification behavior is owned by CRM watchlist state rather than Notify routes alone.
• Documentation guidance only; preserve create/upsert/delete semantics and watchlist relationship model.

Additive façade pilot note

• A first additive façade pilot now exists for watched-case APIs only:
  • pages/api/subscriptions/get-watched-cases.js
  • pages/api/subscriptions/create-watched-case.js
  • pages/api/subscriptions/delete-watched-case.js
• These routes delegate to the existing endpoint handlers.
• Existing endpoint routes remain canonical/stable:
  • pages/api/endpoint/getwatchedcases_api.js
  • pages/api/endpoint/createwatchedcases_api.js
  • pages/api/endpoint/deletewatchedcases_api.js
• No legacy route removal or frontend migration has occurred.

---

12. shared/

Purpose

Represents shared platform components and reusable support primitives that should remain shared regardless of journey grouping.

Primary Journeys Supported

• all journeys indirectly

Typical Integrations

• CRM relay support
• Azure Storage support
• GOV.UK Notify support
• NextAuth/session support
• local-only middleware/helper support

Typical Route Types

• not primarily a journey-owned API route family
• middleware
• helper
• support

Example Existing Routes / Areas

• pages/api/middleware/apiResponse.js
• pages/api/middleware/relayForwarding.js
• pages/api/middleware/relayPolicyPresets.js
• pages/api/middleware/middleware.js

Shared Components Used

• relay helpers
• response helpers
• hash helpers
• signed request helpers
• Azure SDK helpers
• logging helpers
• validation helpers
• auth/session helpers
• Notify helpers

Relationship To Other Groups

• foundational dependency for every journey-owned group

Migration Cautions

• This is primarily a classification for Shared Platform Components, not a recommendation for a user-facing API area.
• Documentation guidance only.

---

Shared Platform Components

The following capabilities should remain classified as Shared Platform Components, not journey-owned APIs:

• relay helpers
  • relayGet(...)
  • relayGetData(...)
  • relay forwarding helpers
  • relay policy presets
• response helpers
  • respondSuccess(...)
  • respondError(...)
• hash helpers
  • path signing
  • integrity validation
• signed request helpers
  • signed GET/POST/DELETE request execution
• Azure Storage helpers
  • blob/container/queue operations
• auth/session helpers
  • session establishment
  • locale resolution support
  • auth-support bootstrap helpers
• Notify helpers
  • send behavior and shared notification composition support
• logging helpers
  • structured/redacted logging support
• validation helpers
  • required-input and route guard helpers

Classification note:

These are shared platform concerns. They should be reused by journey-owned APIs rather than reclassified as journey-owned business capabilities.

---

Journey-to-Group Mapping

This section works at the journey/API-family level only.

It does not classify every individual API file.

Existing API family / journey area	Proposed future group	Classification	Notes
Public search	search/	Natural fit	Strong journey ownership already established in the route map.
Search detail expansion	search/	Natural fit	Closely tied to search contracts and result shaping.
Case details	cases/	Natural fit	Strong case-read ownership, even where current bootstrapping begins through search.
Case messages / notices	cases/	Natural fit	Best understood as case-page content rather than notifications.
Published documents metadata	documents/	Natural fit	Naturally grouped with published document discovery.
Published document download	documents/	Natural fit	Dedicated download boundary already coherent.
My portal dashboard CRM reads	cases/ or representations/ depending on journey	Likely fit	Dashboard is an aggregator, not one clean business capability. Leave journey reads with their owning domains conceptually.
Watched cases / watchlist	subscriptions/	Natural fit	Clear subscription-like relationship model.
Unsubscribe flows	subscriptions/	Natural fit	Closely tied to watchlist/subscription ownership.
Draft appeals	appeals/	Likely fit	Strong journey ownership, but current implementation crosses storage/platform boundaries.
Appeal submission / finalisation	appeals/	Likely fit	Business ownership is appeals, but implementation remains orchestration-heavy.
Representation reads	representations/	Natural fit	Strong journey ownership.
Draft representations	representations/	Likely fit	Strong journey ownership with storage/platform dependency.
Representation submission / finalisation	representations/	Likely fit	Business ownership is clear, but route shape is orchestration-heavy.
Account registration	account/	Natural fit	Clear account lifecycle ownership.
Personal details / account management	account/	Natural fit	Clear account lifecycle ownership.
Authentication / sign-in	auth/	Cross-cutting concern	Foundational platform behavior touching locale, session, and Notify.
Notifications / email	notifications/	Cross-cutting concern	Includes both thin sends and orchestration-heavy flows.
Admin / reporting	admin/	Leave unchanged for now	Already relatively coherent compared with endpoint and file.
Documented middleware / helper routes	shared/ / platform/	Shared / Platform concern	Not journey-owned business APIs.
Health / meta / support routes	platform/	Shared / Platform concern	Platform support rather than business journey ownership.
Legacy catch-all CRM relay families in endpoint/	Depends on owning journey	Leave unchanged for now	Useful as current implementation location, but not a future ownership concept by themselves.
Storage-heavy families in file/	Depends on owning journey plus shared platform	Leave unchanged for now	Current folder is an implementation host, not a stable future ownership model.

---

Architectural Principles

Future development guidance only:

1. Prefer journey ownership over historical folder ownership.
2. Group by business capability rather than by transport or technology alone.
3. Keep integrations behind journey-owned APIs where possible at the architecture level.
4. Reuse shared helpers rather than duplicating infrastructure logic.
5. Preserve API contracts.
6. Preserve current route behavior.
7. Preserve CRM as the source of truth for CRM-owned business data.
8. Preserve Azure Storage ownership boundaries for draft-owned content.
9. Preserve established authorization boundaries and session/bootstrap assumptions.
10. Preserve EN/CY parity and locale-aware behavior.
11. Treat orchestration-heavy routes as business-owned conceptually even when they depend on multiple shared platform capabilities.
12. Do not reorganise stable APIs without explicit business justification and explicit approval.
13. Do not treat endpoint/ or file/ as preferred future ownership models simply because they are current implementation locations.
14. Continue distinguishing between published-document APIs and draft-storage file APIs.

---

Non-Goals

This document explicitly does not approve or recommend:

• implementation
• migrations
• folder restructuring
• route movement
• route renaming
• API deletions
• API consolidation
• merging APIs
• reducing route count
• changing contracts
• changing payload shapes
• changing validation rules
• changing authorization behavior
• changing session behavior
• changing integration boundaries
• changing business behavior

This is architectural direction only.

---

Risks / Cautions

1. This plan is deliberately planning-only.
2. Future grouping concepts should not be mistaken for implementation approval.
3. Several current route families are orchestration-heavy and cross integration boundaries; they are easier to classify architecturally than to reorganise safely.
4. auth/ and notifications/ remain cross-cutting and should not be oversimplified into narrow folder ownership assumptions.
5. endpoint/ and file/ remain current implementation hotspots, but they should be interpreted as historical host folders rather than ideal future ownership concepts.
6. The dashboard remains an aggregation journey and does not justify a separate future grouping here; ownership is clearer when mapped back to cases, representations, subscriptions, and account concerns.
7. Published-document retrieval and draft-storage file handling should remain conceptually distinct.
8. Any future grouping exercise would need explicit migration cautions, but no migration planning is being proposed in this document.

---

Validation Performed

Manual synthesis only.

Performed:

• read the required context files listed above
• confirmed active branch rules and guardrails before drafting
• reused the completed architecture programme as the evidence base
• checked the current top-level pages/api shape only to compare proposed future groups against today’s folder structure without producing a new inventory

Not performed:

• no implementation
• no runtime analysis
• no route-by-route re-inventory
• no refactor proposal
• no migration planning
• no lint/tests, because this is documentation-only planning work

---

Recommendation

Recommended next architecture planning document only:

context/api-rationalisation-planning.md

Suggested purpose:

• evaluate, at a planning level only, where future API families appear structurally duplicated or historically drifted
• define criteria for when a future rationalisation candidate is documentation-worthy
• preserve the same non-goals as this document: no implementation, no migration, no route movement, and no contract change without separate approval

No implementation work is recommended from this document alone.