Robert Bond
@@ -0,0 +1,488 @@
|
||||
# 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
|
||||
|
||||
- characterized
|
||||
- repeated dominant pattern identified
|
||||
- several partial abstractions already present
|
||||
- suitable for incremental implementation
|
||||
|
||||
#### 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
|
||||
|
||||
#### 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**
|
||||
Reference in New Issue
Block a user