Robert Bond
@@ -0,0 +1,378 @@
|
||||
# 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
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
Reference in New Issue
Block a user