14 KiB
Maintainability Adoption Programme
Status
Planning only.
Architecture discovery is complete.
Business-policy discovery is complete.
The remaining work is implementation-led, and future improvements should be delivered as small, incremental, behaviour-preserving adoption slices rather than as new discovery streams.
This document provides the implementation roadmap that emerges naturally from the completed architecture programme.
The programme exists to improve the shared platform supporting:
- existing statutory public information capabilities
- current digital appeal submission
- future supported digital appeal submission processes
- future legislative and case-type enhancements where PEDW extends portal support
It is a planning document only.
It does not recommend large-scale rewrite, redesign, route replacement, framework migration, CRM redesign, or broad modernization.
Required Context Read
The following files were read before drafting this programme:
context/architecture.mdcontext/portal-api-platform-assessment.mdcontext/api-grouping-adoption-roadmap.mdcontext/remaining-architecture-candidates.mdmemory-bank/change-log.md
Additional evidence used from completed characterization work:
- Bilingual CRM Display Resolution Audit
- Bilingual Navigation & Link Resolution Audit
These were treated as completed evidence inputs rather than reopened as new discovery exercises.
Programme Status
Discovery Programme Position
The PEDW architecture programme should now be understood as having completed its main discovery and characterization work.
Current state:
- architecture discovery: complete
- business-policy discovery: complete
- principal policy candidates: established
- principal presentation and compatibility candidates: characterized
- remaining work: adoption planning, extraction sequencing, bounded implementation slices, and validation-led runtime adoption
This means future work should no longer be framed as:
- broad discovery
- open-ended architecture hunting
- large speculative redesign
It should instead be framed as:
- characterization-backed implementation planning
- incremental helper extraction where justified
- selective runtime adoption of already-proven seams
- maintainability improvements that preserve current behaviour
Maintainability Principles
The maintainability programme should follow this sequence:
- Characterize
- Validate
- Extract / Add
- Adopt
Interpretation
Characterize
Understand the existing behaviour first.
Capture repeated patterns, implementation differences, fallbacks, risks, and current ownership before introducing a shared abstraction.
Validate
Confirm that the proposed seam is real, that behaviour is stable enough to preserve, and that the slice boundary is safe.
Extract / Add
Prefer small compatibility helpers or additive abstractions over replacement.
Adopt
Adopt new abstractions incrementally in bounded vertical slices.
Do not attempt broad retrospective migration in one change.
Programme Prohibitions
Future maintainability work should not default to:
- rewrite
- replace
- redesign
- modernize
without explicit approval.
These approaches carry materially higher regression risk and do not match the refactor branch discipline.
Workstream Classification
The maintainability programme now naturally groups into a small number of implementation workstreams.
Each workstream below reflects already-characterized architecture boundaries or compatibility seams.
1. Domain Layer Adoption
Objective
Increase runtime adoption of already-proven domain and policy seams without expanding them into a broader unproven domain model.
Architectural Classification
- Business Decision Model
- narrow domain-layer adoption
Representative Areas
- Appeal Type Policy
- Representation Entry Policy
- Representation Type Availability
Current Maturity
- extraction substantially complete
- characterization confidence high
- runtime adoption still selective and uneven across consumers
Implementation Strategy
- preserve the current intentionally narrow domain-layer scope
- favour consumer-by-consumer runtime adoption
- avoid converting surrounding compatibility or presentation code into faux domain logic
- protect behaviour with bounded characterization and targeted validation when new adoption slices occur
Expected Maintenance Benefit
- clearer ownership for true business-rule logic
- less repeated policy branching in UI/loaders/routes
- safer future changes in policy-sensitive areas
2. CRM Display Infrastructure
Objective
Create a clearer single source of truth for CRM-driven bilingual display behaviour while preserving current runtime output.
Architectural Classification
- CRM Compatibility Model
- Presentation Infrastructure
Representative Areas
- CRM formatted values
- lookup translation
- JSONPath-based translation access
- picklists
- status labels
- stage labels
- appeal type labels
- specialist process labels
- LPA display
Current Maturity
- completed
- shared resolver introduced
- helper test coverage added
- helper contract verified and corrected
- compatible consumers adopted across admin, search, My Portal, and summary types
- stale JSONPath import cleanup completed where safe
- behaviour-preserving migration completed
Implementation Strategy
- start from the dominant existing compatibility pattern rather than designing a new model from scratch
- prefer additive shared resolvers over broad replacement
- adopt first in bounded, read-only display families
- preserve current fallback behaviour per consumer unless an explicit standardization decision is approved
Status
Completed.
Delivered in this workstream:
- shared resolver introduced
- helper test coverage
- helper contract verified and corrected
- adoption across:
- admin
- search
- My Portal
- summary types
- stale JSONPath import cleanup
- behaviour-preserving migration
Remaining JSONPath usage in adopted areas is intentional where it falls outside the helper boundary.
That includes concerns such as:
- keyed lookup translation
- project-type list translation
- hyperlink / website rendering
- mixed presentation rows
- lifecycle / status / post-decision interpretation
- other presentation-specific derived values
Expected Maintenance Benefit
- reduced duplication of display-resolution logic
- improved EN/CY consistency
- improved maintainability of CRM-driven presentation surfaces
- lower risk of display drift across search, case, admin, my portal, and PDF consumers
3. Navigation Infrastructure
Objective
Establish a clearer single source of truth for bilingual navigation behaviour across public, my portal, auth, and case-navigation journeys.
Architectural Classification
- Routing / Navigation Infrastructure
- Presentation / i18n Infrastructure
Representative Areas
- route resolution
- locale-aware links
- breadcrumbs
- callback URLs
- redirects
- search/case navigation
- my portal/public navigation
- bilingual back-link and step-back behaviour
Current Maturity
- characterized
- repeated locale-switching and route-construction logic identified
- partial routing helper seams already exist
- recommended for incremental implementation
Implementation Strategy
- extend the newer routing-helper seam rather than adding a competing navigation model
- adopt one journey family at a time
- keep internal-route resolution separate from CRM display resolution
- treat auth callback/redirect handling as compatibility-sensitive and adopt cautiously
Expected Maintenance Benefit
- less duplicated Welsh/English route selection
- clearer route ownership and query preservation rules
- reduced EN/CY navigation drift
- safer future route additions and journey updates
4. API Journey Grouping
Objective
Continue the additive grouping approach only where it is already proven to be low-risk and maintainable.
Architectural Classification
- API Platform Maintainability
- Route Ownership / Journey Grouping
Current Maturity
- planning and pilot work substantially proven
- bounded adoption slices completed for selected read families
- the read-style rollout has reached its natural boundary
Implementation Strategy
- continue using grouped routes for new bounded APIs where ownership is clear
- prefer additive façade grouping for new read-oriented journey families
- keep existing canonical handlers stable behind the façade where appropriate
- avoid broad retrospective rollout into workflow/orchestration-heavy areas
Boundary Guidance
Do not treat this workstream as permission to:
- reorganize all historical APIs
- group orchestration-heavy families using the same pattern
- migrate contract-critical routes in bulk
Expected Maintenance Benefit
- improved findability
- clearer journey ownership
- safer future route placement
- better consistency in newer API work without destabilising established orchestration families
Relative Priority
The recommended implementation priority order is:
- Domain Layer Adoption
- CRM Display Infrastructure
- Navigation Infrastructure
- API Journey Grouping
Priority Rationale
1. Domain Layer Adoption
This has the strongest established business-value boundary and the clearest policy ownership.
The architecture programme already proved these seams, so the remaining work is mainly controlled runtime adoption.
2. CRM Display Infrastructure
This area shows high duplication with one dominant repeated pattern and already-characterized opportunities for shared compatibility helpers.
It offers a strong maintainability return without requiring business-rule change.
3. Navigation Infrastructure
This area is also strongly justified, but the implementation landscape is more mixed because it spans:
- internal routes
- breadcrumbs
- auth callbacks
- redirects
- public/myportal variants
- external bilingual links
That makes it slightly broader than CRM display infrastructure and therefore better positioned after CRM display adoption begins.
4. API Journey Grouping
This remains valuable, but the roadmap already shows that the current additive read-style rollout has reached a natural stop point.
This workstream should continue selectively, especially for new bounded read families, but should not dominate the programme at the expense of higher-value shared maintainability seams.
Guiding Principles
Future maintainability work should favour:
- single source of truth
- reusable abstractions
- behaviour preservation
- incremental adoption
- characterization-first implementation
- bounded vertical slices
- additive compatibility helpers over replacement
- explicit validation evidence for sensitive flows
Where multiple implementations already coexist, the programme should prefer:
- proving the dominant pattern
- extracting the smallest safe shared seam
- adopting it in one narrow consumer family first
rather than imposing a large harmonization effort in one change.
Explicit Non-Goals
This programme is not attempting:
- Domain-Driven Design conversion
- framework migration
- large-scale rewrites
- folder restructuring
- API replacement
- CRM redesign
- broad route migration
- aesthetic modernization for its own sake
It is a maintainability adoption programme, not a transformation programme.
Adoption Model
The intended shape of future work is:
characterized boundary
↓
small helper / façade / compatibility seam
↓
bounded consumer adoption
↓
validation
↓
repeat only where evidence justifies it
This should apply across:
- domain-layer adoption
- CRM display infrastructure
- navigation infrastructure
- API grouping
Relationship to Existing Architecture
This document does not replace the existing architecture records.
It sits on top of them as the implementation roadmap for the next phase.
Relationship summary:
context/architecture.md- defines the programme phase as adoption planning
context/portal-api-platform-assessment.md- establishes API maintainability problems as findability, ownership clarity, consistency, and reuse discipline
context/api-grouping-adoption-roadmap.md- provides the bounded guidance for additive API grouping and its natural boundary
context/remaining-architecture-candidates.md- confirms discovery is complete and remaining work is adoption-planning, characterization coverage, extraction planning, and adoption
- completed bilingual audits
- provide evidence that CRM display infrastructure and navigation infrastructure are now justified maintainability workstreams
Recommended Next Planning / Implementation Discipline
When future slices are proposed, each should state:
- the workstream it belongs to
- the characterized seam being adopted
- the smallest bounded consumer scope
- the preserved behaviour constraints
- the validation evidence required
Preferred slice types:
- one helper extraction
- one consumer-family adoption
- one compatibility seam formalization
- one bounded API grouping façade adoption
Avoid mixed multi-workstream slices unless the relationship is already proven and the risk is low.
Programme Recommendation
PEDW should now treat maintainability improvement as a planned adoption programme rather than as a continuing discovery exercise.
The highest-value future work is likely to come from:
- continued narrow domain-layer adoption
- incremental CRM display infrastructure adoption
- incremental navigation infrastructure adoption
- selective continuation of additive API grouping where the route family is bounded and non-orchestration-heavy
The overall rule remains:
preserve behaviour, improve clarity, and adopt small reusable seams incrementally.
Relationship to Implementation Governance
This document defines what maintainability workstreams should be advanced and in what relative order.
The standard execution model for future implementation slices is recorded separately in:
context/implementation-governance.md
That governance document defines how each future slice should be:
- planned
- branched
- executed
- validated
- documented
- reported
The maintainability programme and implementation governance documents should therefore be read together:
- maintainability adoption programme -> what to advance
- implementation governance -> how to execute each slice safely