pedwfrontend/context/api-grouping-adoption-roadmap.md

API Grouping Adoption Roadmap

Status

Planning only.

Pilot status update (2026-06-25):

• first additive grouping façade pilot implemented for watched-case APIs under pages/api/subscriptions/
• first internal consumer (actions/services/portalDirectService.js watched-case methods) now targets the grouped façade routes
• the active watched-case vertical slice now includes grouped adoption for both normal watched-case reads and proxy watched-case reads used by the current UI journey
• second additive grouping façade vertical slice implemented for the active published-documents metadata journey under pages/api/documents/
• active published-document metadata consumer (actions/services/searchDirectService.js) now targets grouped documents façade routes for details, paged details, and document-type reads
• published document download remains on the existing grouped runtime path pages/api/documents/download/[id].js
• legacy document metadata endpoint routes remain canonical and stable behind the additive façade wrappers
• third additive grouping façade vertical slice implemented for the active Public Search results journey under pages/api/search/
• active public search consumer (actions/services/searchDirectService.js) now targets grouped search façade routes for the proven in-scope public results path
• legacy public search endpoint routes remain canonical and stable behind the additive façade wrappers
• legacy watched-case endpoint routes remain canonical and stable
• no old route removal or migration has occurred
• runtime behaviour is intended to remain unchanged because the grouped routes delegate to the existing handlers

This document describes how PEDW could gradually adopt the future journey-owned API grouping model over time without disrupting existing functionality.

It is an architectural roadmap only.

It does not recommend implementation, migration, route movement, route renaming, API deletion, consolidation, contract change, or behaviour change.

---

Required Context Read

The following files were read before drafting this roadmap:

• context/api-grouping-plan.md
• 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-adoption-roadmap.md
• memory-bank/change-log.md

---

Findings

• The completed architecture programme already established that PEDW’s API platform is structurally smaller than its route count first suggests.
• The main maintainability problems are already known:
  • findability
  • ownership clarity
  • consistency
  • reuse discipline
• The current runtime is stable even though folder ownership is historically mixed.
• The current top-level API shape still reflects historical growth more than clean journey ownership, especially in:
  • pages/api/endpoint
  • pages/api/file
• The route map, journey map, and API grouping plan already support a journey-first conceptual model without requiring physical route movement.
• The strongest safe planning assumption is therefore:

PEDW should adopt future journey-owned API grouping gradually through future development guidance, improved documentation, and incremental consistency rather than large-scale migration.

---

Adoption Philosophy

PEDW should favour gradual evolution over large structural change.

Why:

1. The current platform is already live and stable.
2. Many APIs are contract-critical even where current folder ownership is historically inconsistent.
3. Several route families are orchestration-heavy and cross multiple integrations, making physical reorganisation riskier than conceptual reclassification.
4. The completed architecture programme has already shown that the main problem is not missing discovery; it is making ownership and maintainability clearer.

For that reason, PEDW should prefer:

• gradual evolution
• behaviour preservation
• contract preservation
• incremental consistency
• reuse of shared helpers
• documentation-led clarity

over:

• large restructures
• wholesale folder moves
• API rewrites
• mass renaming
• cosmetic reorganisation without delivery value

Adoption guidance:

• existing APIs should remain stable
• existing routes should continue to work
• existing URLs should continue to work
• existing contracts should continue to work
• future grouping should emerge naturally as future work touches relevant areas

---

Adoption Stages

Stage 1 — Current State

Purpose

Record today’s platform as the baseline for future adoption thinking.

Current State Summary

• the API platform reflects historical growth
• current top-level folders remain implementation hosts rather than clean business ownership boundaries
• ownership is mixed across business journeys, integrations, and shared support concerns
• the runtime is stable and should be preserved

Architecture Notes

• endpoint/ remains the main historical CRM relay catch-all
• file/ remains the main secondary storage/orchestration catch-all
• smaller families such as admin/, documents/, and auth/ are more coherent, though not always perfectly isolated
• shared helpers and route patterns already exist and provide a safer basis for future consistency than folder movement alone

Roadmap Meaning

Stage 1 is not a problem statement that justifies migration.

It is the baseline that explains why PEDW should improve ownership clarity without destabilising the current runtime.

---

Stage 2 — Future Development Guidance

Purpose

Guide future API work so that PEDW gradually becomes more journey-owned over time without requiring broad reorganisation.

Guidance

• new APIs should naturally follow journey ownership
• new work should start from the journey-owned model before considering current folder habits
• new APIs should reuse existing shared helpers where suitable
• avoid creating additional catch-all folders
• avoid copying historical direct-wrapper patterns where shared helpers already exist
• keep integrations behind journey-owned API boundaries conceptually, even when current files remain where they are
• preserve published-document and draft-storage distinctions
• preserve established auth/session and authorization boundaries

Practical Interpretation

This stage does not mean:

• move existing routes now
• rename existing routes now
• rewrite older APIs now

It means:

• when future work naturally touches an area, use the future grouping plan as the conceptual ownership guide
• prefer additive clarity over structural churn

Proven pilot pattern

• The watched-case subscriptions pilot demonstrates a low-risk adoption shape:
  • add grouped façade routes in a journey-owned folder
  • delegate directly to the existing canonical handlers
  • keep existing routes live and unchanged
  • adopt the grouped routes incrementally through a carefully selected internal consumer first
• This should be treated as additive proof of the grouping model, not as rationalisation or deprecation.

Incremental adoption proof point

• The first internal consumer adoption is now in place for watched-case methods in actions/services/portalDirectService.js.
• For the intended watched-case journey scope, the active vertical slice now covers:
  • getWatchedCases
  • getWatchedCasesProxy
  • createWatchedCases
  • deleteWatchedCases
• Legacy watched-case endpoint routes remain the canonical implementations behind the façade.
• No route deprecation, removal, or contract migration has occurred.
• This validates that grouped journey-owned routes can be introduced first and then adopted incrementally without changing runtime behaviour.

Current pilot completion meaning

• For this pilot, a complete watched-case/subscriptions vertical slice means:
  • grouped subscriptions façade routes exist for the active watched-case journey calls
  • actions/services/portalDirectService.js targets those grouped routes for the active watched-case journey methods
  • legacy endpoint handlers remain present and canonical behind the façade
  • runtime behaviour remains unchanged through delegation
• deletewatchedcasesproxy_api remains a legacy/support route outside the grouped pilot scope because it is not part of the currently adopted normal watched-case service path.

Additional vertical-slice proof point — published documents

• The active published-documents journey now has a second complete additive grouping slice for metadata discovery only:
  • grouped façade routes exist for the active metadata/type reads under pages/api/documents/
  • actions/services/searchDirectService.js targets those grouped routes for:
    • getSearchDocumentDetails
    • getSearchDocumentDetailsPaged
    • getSearchDocumentTypes
  • legacy endpoint handlers remain present and canonical behind the façade:
    • pages/api/endpoint/getsearchdocumentdetails_api.js
    • pages/api/endpoint/getsearchdocumentdetailspaged_api.js
    • pages/api/endpoint/getsearchdocumentTypes_api.js
  • runtime behaviour remains unchanged through direct delegation and unchanged service-layer query contracts
• The active bounded audit also established that:
  • the current UI document journey is routed through components/case/documents.js
  • the current common metadata service layer is actions/services/searchDirectService.js
  • the existing grouped route pages/api/documents/download/[id].js remains the runtime download path and was intentionally left unchanged
  • getsearchdocumenthistory_api.js and getsearchdocumenthistorypaged_api.js remain present as legacy/support routes outside the active grouped adoption scope because they were not surfaced in the currently active UI journey
• For this documents slice, a complete vertical grouping slice means:
  • active document metadata/type journey calls have grouped façade routes
  • the active common service layer uses those grouped routes
  • legacy handlers remain present and canonical
  • download behaviour remains unchanged
  • no route migration, deletion, or contract change has occurred

Additional vertical-slice proof point — Public Search

• The active Public Search journey now has a third complete additive grouping slice for the bounded public results path:
  • grouped façade routes exist under pages/api/search/ for the proven active service calls:
    • basic-paged
    • advanced
    • advanced-paged
    • basic-details-paged
  • actions/services/searchDirectService.js targets those grouped routes for:
    • getBasicSearchPaged
    • getAdvancedSearch
    • getAdvancedSearchPaged
    • getBasicSearchDetailsPaged
  • legacy endpoint handlers remain present and canonical behind the façade:
    • pages/api/endpoint/getbasicsearchpaged_api.js
    • pages/api/endpoint/getadvancedsearch_api.js
    • pages/api/endpoint/getadvancedsearchpaged_api.js
    • pages/api/endpoint/getbasicsearchdetailspaged_api.js
  • runtime behaviour remains unchanged through direct delegation and unchanged service-layer query contracts
• The bounded public-search audit also established that:
  • the active public results UI is driven through components/search/searchresults.js
  • the common service layer is actions/services/searchDirectService.js
  • paged basic results are active in the public results path
  • advanced search is in scope because pages/advancedsearchresults.js actively uses the advanced bootstrap route and the shared results UI actively uses the advanced paged route
  • paged search-detail expansion is in scope because the active results UI uses getSearchDetailsPaged(...), which calls getBasicSearchDetailsPaged(...)
  • the following routes remain outside this grouped adoption scope because they belong to adjacent or excluded journeys rather than the active bounded public results path:
    • getbasicsearch_api.js (used for adjacent case-detail bootstrap and other non-results contexts)
    • getbasicsearchdetails_api.js (used for adjacent case-detail/bootstrap detail expansion)
    • address-search variants
    • DNS search variants
    • myportal search pages
• For this Public Search slice, a complete vertical grouping slice means:
  • active public results journey calls have grouped façade routes
  • the active common service layer uses those grouped routes
  • legacy handlers remain present and canonical
  • excluded adjacent search journeys remain unchanged
  • no route migration, deletion, or contract change has occurred

API Grouping Façade Rollout Checkpoint

• The first successful façade slices now establish a proven additive rollout pattern for:
  • subscriptions / watched cases
  • documents / published document metadata
  • public search results
• Proven runtime shape:

UI journey
→ existing service layer
→ grouped façade route
→ legacy canonical handler
→ unchanged integration behaviour

• Proven implementation pattern:
  • audit the active journey path first
  • identify the existing owning/common service layer already used by that path
  • add grouped façade routes only for the proven in-scope active calls
  • implement each grouped route as a tiny wrapper that delegates directly to the existing legacy handler
  • keep the legacy handler as the canonical implementation
  • adopt the grouped route in the existing service layer only where the active journey path is proven and low-risk
  • leave adjacent, inactive, support, or orchestration-heavy routes out of scope unless separately justified
  • prove the slice with lightweight characterization tests covering delegation, service adoption, retained legacy handlers, and unchanged scope boundaries
• Important interpretation:
  • this checkpoint proves a safe rollout pattern for additive façade grouping
  • it does not approve route removal
  • it does not approve handler replacement
  • it does not approve broad migration
  • it does not approve grouping of more complex API families without another bounded audit

Vertical façade slice completion criteria

• A vertical façade slice should be treated as complete only when:
  • active journey paths are audited
  • grouped façade routes exist for the in-scope active routes only
  • the service layer adopts the grouped routes where safe and proven
  • legacy handlers remain present and canonical behind the façade
  • inactive or support routes are explicitly left out of scope where they are not part of the active adopted path
  • characterization tests prove façade delegation and service-layer adoption
  • characterization tests do not imply that legacy handlers can be removed
  • documentation records the exact scope, completion meaning, exclusions, and non-goals
• A slice is not complete merely because grouped files exist.
• Completion requires both bounded adoption evidence and explicit documentation of what remains outside scope.

Do not group yet criteria

• Grouping should be delayed when any of the following apply:
  • no clear service layer exists
  • active ownership is unclear
  • the route is orchestration-heavy
  • the route crosses storage + queue + CRM boundaries
  • the route is auth/session critical
  • the route is not proven active in a bounded current journey
  • grouping would require frontend refactor rather than additive service-level adoption
  • grouping would require contract change
• In these cases, documentation may still classify the area conceptually, but additive façade rollout should wait for a safer bounded slice.

---

Stage 3 — Documentation Maturity

Purpose

Improve maintainability through better documentation and route ownership guidance before any physical restructuring is ever considered.

Maturity Outcomes

• improved maintainer guidance
• improved route ownership clarity
• improved discoverability
• improved architectural consistency in how new work is described and reviewed
• better onboarding for contributors who need to understand where to start

Examples of Documentation-Led Adoption

• route ownership described by journey rather than folder alone
• shared platform helpers clearly separated from business APIs
• cross-cutting concerns such as auth and notifications documented as cross-cutting rather than forced into one business domain
• future grouping candidates captured as architectural guidance only

Important Constraint

This stage improves understanding without moving routes.

---

Stage 4 — Future Opportunities

Purpose

Record possible future opportunities that could align with the grouping model if future work naturally justifies them.

Possible Future Opportunities

• selective grouping within areas already being changed for other approved reasons
• helper extraction where duplication remains visible
• improved shared platform reuse across journey-owned APIs
• stronger consistency in naming, ownership notes, and maintainer entry guidance
• clearer distinction between journey-owned APIs and shared/platform concerns

Constraint

These are future opportunities only.

They are not implementation recommendations.

They do not approve:

• route movement
• file movement
• migrations
• refactoring programmes
• API rewrites

---

Adoption Principles

1. Preserve stable APIs.
2. Preserve contracts.
3. Preserve integrations.
4. Preserve CRM as the source of truth for CRM-owned business data.
5. Preserve Azure Storage ownership boundaries for draft-owned content.
6. Preserve established auth/session and authorization boundaries.
7. Prefer additive improvements.
8. Avoid unnecessary churn.
9. Improve findability first.
10. Improve consistency second.
11. Reuse shared helpers instead of duplicating infrastructure logic.
12. Use journey ownership as the conceptual guide for future work.
13. Consider physical grouping only when future approved work naturally touches an area.
14. Never move APIs solely for cosmetic reasons.
15. Do not force cross-cutting concerns into one journey-owned bucket.
16. Continue treating shared/platform capabilities as shared platform concerns rather than business-domain ownership.

---

Decision Matrix

Situation	Guidance
New API	Place it conceptually within the journey-owned model first, then implement using the safest existing route/helper patterns.
Existing stable API	Leave unchanged.
Existing API being enhanced	Consider alignment with journey ownership in documentation and helper usage, without assuming route movement.
Shared infrastructure	Keep in shared/platform concern classification.
Cross-cutting concern	Avoid forcing it into one journey if its real ownership is platform-wide or multi-journey.
Historical catch-all folder	Treat it as a current host location, not as the preferred future ownership model.
Orchestration-heavy route	Classify conceptually by business journey, but preserve existing integration and sequencing behavior.
Documentation update	Improve findability and ownership clarity before considering any structural change.
Cosmetic restructuring idea	Do not pursue unless separately justified by future approved work.

---

Success Measures

Success should be understood qualitatively at architecture and maintainability level, not as an implementation delivery target.

Indicators of success:

• developers can find relevant APIs faster
• maintainers can identify likely owning journeys more easily
• shared infrastructure code is reused more consistently
• journey ownership becomes clearer in future documentation and code review discussions
• onboarding becomes simpler because route ownership is easier to explain
• maintenance effort is reduced through clearer patterns and less duplicated infrastructure logic
• future API additions align more naturally with business capability rather than historical folder drift

Avoid treating success as:

• number of routes moved
• number of folders renamed
• reduction in route count
• migration completion percentage

---

Non-Goals

This roadmap explicitly does not approve or recommend:

• migrations
• implementation
• route movement
• route renaming
• API deletion
• API consolidation
• folder restructuring
• refactoring programmes
• mass renaming
• contract changes
• behaviour changes

This roadmap defines architectural direction, not delivery.

---

Risks / Cautions

1. This roadmap is intentionally architecture-only.
2. It should not be mistaken for an implementation plan.
3. Stable runtime behavior matters more than conceptual neatness.
4. Several PEDW API areas remain orchestration-heavy and cross integration boundaries; conceptual grouping is safer than physical reorganisation.
5. endpoint/ and file/ remain historically important host folders even though they are not ideal future ownership concepts.
6. auth/ and notifications/ remain cross-cutting concerns and should not be over-simplified.
7. Dashboard-related APIs are aggregation-oriented and should be mapped back to owning journeys rather than treated as a separate long-term grouping target.
8. Future adoption should happen through natural change pressure, not through standalone cosmetic restructuring.

---

Validation Performed

Manual synthesis only.

Performed:

• read the required roadmap context listed above
• reused the completed architecture programme as the evidence base
• reused the completed API grouping plan rather than reopening discovery
• kept the roadmap at architecture-roadmap level only

Not performed:

• no new API inspection
• no new API inventory
• no implementation design
• no migration proposal
• no refactor proposal
• no lint/tests, because this is documentation-only planning work

---

Recommendation

Recommended next architecture planning document only:

context/api-maintainer-guidance-v2.md

Suggested purpose:

• extend the existing maintainer guidance with clearer decision support for future API additions
• strengthen journey-owned ownership cues and shared-helper selection guidance
• improve onboarding and change-entry clarity without recommending implementation or restructuring

No implementation work is recommended from this roadmap alone.