408 lines
17 KiB
Markdown
408 lines
17 KiB
Markdown
# 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
|
||
- 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
|
||
|
||
---
|
||
|
||
### 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.
|