# 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.md` - `context/portal-api-platform-assessment.md` - `context/api-grouping-adoption-roadmap.md` - `context/remaining-architecture-candidates.md` - `memory-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: 1. **Characterize** 2. **Validate** 3. **Extract / Add** 4. **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: 1. **Domain Layer Adoption** 2. **CRM Display Infrastructure** 3. **Navigation Infrastructure** 4. **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: ```text 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: 1. continued narrow domain-layer adoption 2. incremental CRM display infrastructure adoption 3. incremental navigation infrastructure adoption 4. 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**