916 lines
29 KiB
Markdown
916 lines
29 KiB
Markdown
# 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:
|
||
|
||
```text
|
||
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.
|