520 lines
14 KiB
Markdown
520 lines
14 KiB
Markdown
# 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**
|