# NGauge Modernization TODOs

Last updated: 2026-03-10
Status legend: [ ] not started, [~] in progress, [x] done

Effort scale: S (small day), M (2-3 days), L (week), XL (2+ weeks)
Owner roles: ArchLead, DBArch, CartLead, TestLead, DevOps

---

# SPRINT 1 (Weeks 1-2): Foundation & Safety Rails
**Goal:** Establish safety metrics, document risks, and prepare team for major rewrites.

---

## SPRINT 1: Foundation & Safety Rails (1–2 weeks)
**Owner:** ArchLead, DevOps

### A) Program & Governance
- [ ] [S] Confirm baseline branch and strategy | ArchLead | Kick-off
- [ ] [S] Publish risk register with owner per domain | ArchLead | Mid-sprint
- [ ] [S] Define commit/PR naming and rollback checklist | DevOps + ArchLead | End sprint
- **Gate 1 Acceptance:** Risk register signed off, all owners assigned, rollback plans rehearsed

### B) Baseline Capture
- [ ] [M] Run PHPStan on full codebase; capture baseline | TestLead | Early
- [ ] [M] Capture test baseline for cart/order/payment/shipping flows | TestLead | Early
- [ ] [S] Document current async/queue usage on hot paths | ArchLead | Early
- [ ] [M] Produce inventory of composite-key (id+language) tables/relations | DBArch | Mid-sprint
- [ ] [S] List top 20 code smell hotspots (large models/controllers) | ArchLead | Mid-sprint
- **Gate 1 Acceptance:** All baselines captured in shared wiki/dashboard

---

## SPRINT 2: Syntax & Deprecation Cleanup (2–3 weeks)
**Owner:** CartLead (cart focus), TestLead (validation)

### C) Legacy Syntax Modernization
- [ ] [L] Replace array() → [] in cart & product domains (50+ files) | CartLead | Early
- [ ] [M] Replace endif/endfor/endwhile → } in views & controllers | CartLead | Early
- [ ] [M] Add scalar/return types to top 30 core models | CartLead | Mid-sprint
- [ ] [S] Remove dead/commented code in cart controllers | CartLead | Mid-sprint
- [ ] [S] Flag and document remaining old patterns for future cleanup | ArchLead | End sprint
- **Gate 2 Acceptance:** PHPStan improves 2+ levels, cart tests pass, no new warnings

### D) Deprecation Path
- [ ] [M] Migrate Queue::{ErrorEvent, RetryableJob, Job} to interfaces | DevOps | Mid-sprint
- [ ] [S] Update deprecated queue component usage on critical paths | CartLead | End sprint
- **Gate 2 Acceptance:** No deprecation warnings on hot paths

---

## SPRINT 3: Data Optimization & Multi-Language Foundation (3–4 weeks)
**Owner:** DBArch, CartLead

### E) Data Structure Audit & Migration Plan
- [ ] [M] Field-level classification: relational vs JSON vs hybrid | DBArch | Early
- [ ] [M] Tag all queried JSON fields; rank by access frequency | DBArch | Early
- [ ] [M] Design SEO field split: core relational + extended JSON | DBArch + CartLead | Mid-sprint
- [ ] [L] Create migration scripts for critical JSON → column moves (cartlines, products) | DBArch | Mid-sprint

### F) Cart-Specific Data Work
- [ ] [M] Extract ERP IDs, shipping group IDs, supplier IDs from JSON to columns | DBArch + CartLead | Mid-sprint
- [ ] [S] Add generated indexes for remaining JSON query paths | DBArch | End sprint
- [ ] [M] Benchmark pre/post query performance on cart list/search | TestLead | End sprint
- **Gate 3A Acceptance:** Data migration scripts tested, benchmarks show improvement or parity

### G) Multi-Language Infrastructure
- [ ] [M] Inventory all models using id+language PK; map dependencies | DBArch | Early
- [ ] [L] Design & implement translation storage helper trait | ArchLead + DBArch | Mid-sprint
- [ ] [M] Design compatibility layer supporting legacy language contracts | ArchLead | Mid-sprint
- [ ] [S] Document fallback policy (requested lang → default lang) | ArchLead | End sprint
- **Gate 3B Acceptance:** Translation helper passes unit tests, compatibility design reviewed

### H) Multi-Language Pilot Prep
- [ ] [M] Create pilot migration scripts for sys_country and realexcodes | DBArch | End sprint
- [ ] [S] Write rollback toggle test (read legacy path vs new path) | TestLead | End sprint
- **Gate 3B Acceptance:** Pilot scripts reviewed and rollback toggle proven

---

## SPRINT 4: Multi-Language Pilot & Cart Decomposition (2–3 weeks)
**Owner:** DBArch (pilot), CartLead (decomposition)

### I) Multi-Language Pilot Execution
- [ ] [M] Execute sys_country migration; dual-write enabled | DBArch | Early
- [ ] [M] Validate CRUD/search parity; run compatibility layer tests | TestLead | Mid-sprint
- [ ] [S] Run rollback toggle; verify revert works cleanly | DevOps | Mid-sprint
- [ ] [M] Execute realexcodes/sys_errors migration; repeat parity checks | DBArch | Mid-sprint
- [ ] [S] Remove temporary compatibility shims for pilot tables (post-stability window) | DBArch | End sprint
- **Gate 4A Acceptance:** Pilot tables migrated, parity proven, rollback tested and retired

### J) Cart Model Decomposition
- [ ] [L] Split Cartsbe (1,076 lines) into Cart, Order, Quote models (<300 lines each) | CartLead | Early
- [ ] [M] Extract PricingService, ShippingService, OrderService | CartLead | Mid-sprint
- [ ] [M] Consolidate duplicated cart extended/data patterns | CartLead | Mid-sprint
- [ ] [M] Refactor CartController to orchestration layer (<300 lines) | CartLead | Mid-sprint
- [ ] [M] Write integration tests locking cart behavior before extraction | TestLead | End sprint
- **Gate 4B Acceptance:** Cart tests pass, controller/model complexity reduced, services testable in isolation

---

## SPRINT 5: Cart Module Extraction (2 weeks)
**Owner:** CartLead, ArchLead

### K) Module Scaffolding
- [ ] [S] Create portalpeople/ngauge-cart repository in Azure | DevOps | Early
- [ ] [M] Set namespace (PortalPeople\Cart\), PSR-4 autoload, composer.json | CartLead | Early
- [ ] [S] Add module config, bootstrap, and dependency wiring | CartLead | Early

### L) Domain Migration to Module
- [ ] [M] Move Cart, Order, Quote models to module namespace | CartLead | Mid-sprint
- [ ] [M] Move CartService, PricingService, ShippingService, OrderService to module | CartLead | Mid-sprint
- [ ] [M] Move controllers/views (admin + runtime) to module | CartLead | Mid-sprint
- [ ] [M] Move integration tests into module test suite | TestLead | Mid-sprint
- **Gate 5A Acceptance:** Module runs standalone in isolated environment; all tests pass

### M) Integration with NGauge_Base
- [ ] [M] Add module as composer dependency in NGauge_Base | DevOps | End sprint
- [ ] [M] Update app config to load Cart module | CartLead | End sprint
- [ ] [M] Create facade classes (Cartsbe, Cartlines, CartController) for backward compat | CartLead | End sprint
- [ ] [M] Switch internal cart routes to module controller (incremental) | CartLead | End sprint
- **Gate 5B Acceptance:** Legacy routes, class names, and APIs still work; no checkout regression

---

## SPRINT 6+: Stabilization, Consolidation, Additional Modules (ongoing)

### N) Stability & Quality
- [ ] [M] Run full regression suite; fix any edge cases | TestLead | Week 1
- [ ] [S] Remove facade/compat layers after stability window | CartLead | Week 2+
- [ ] [M] Consolidate duplicate base/search patterns in remaining models | ArchLead | Week 2+

### O) Medium-Risk Multi-Language Rollout (parallel track)
- [ ] [L] Migrate content/catalog domains (menu/pagegroup/categories) | DBArch | Weeks 1–2
- [ ] [M] Rewrite search models + relations away from language-as-identity | CartLead + ArchLead | Weeks 1–2
- [ ] [M] Validate checkout/payment flows with new language schema | TestLead | Week 2

### P) Additional Module Extractions (future phases)
- [ ] Products module (similar pattern to Cart)
- [ ] Accounts/Users module
- [ ] Shipping/Delivery module

### Q) Deferred Dependency Replacements (planned)
- [ ] [S] Confirm replacement target and scope for abandoned `alexantr/yii2-elfinder` migration to `mihaildev/yii2-elfinder` | ArchLead | Backlog
- [ ] [M] Update composer dependency and adapt current widget integrations | CartLead | Backlog
- [ ] [M] Test file picker and TinyMCE image/file selection flows end-to-end | TestLead | Backlog
- [ ] [S] Remove old package and run full regression on affected admin pages | CartLead + TestLead | Backlog
- [ ] [S] Deploy to dev/stage, monitor, then promote to production | DevOps + TestLead | Backlog
- **Risk:** Integration differences in current file picker/TinyMCE hooks
- **Rollback:** Revert `composer.lock` and widget integration changes

### R) Deferred Frontend Framework Upgrade (planned)
- [ ] [S] Confirm Bootstrap target version and scope (5 now, 6 readiness review) | ArchLead | Backlog
- [ ] [M] Inventory Bootstrap 4 usage across templates/components (grid, utilities, forms, nav, modals) | CartLead | Backlog
- [ ] [M] Build a breaking-change checklist (class removals/renames, JS plugin/API differences) | ArchLead + TestLead | Backlog
- [ ] [L] Migrate high-use layouts/components from Bootstrap 4 to target version | CartLead | Backlog
- [ ] [M] Run end-to-end UI/UX verification and log all visual/functional regressions by severity | TestLead | Backlog
- [ ] [M] Fix and retest all critical/high regressions before release sign-off | CartLead + TestLead | Backlog
- **Risk:** UI regressions from Bootstrap class/API changes and JS behavior differences
- **Rollback:** Revert frontend template/asset changes and dependency lockfile

---

## Verification Gates Summary

| Gate | Criteria | Owner |
|------|----------|-------|
| **1** | Risk register signed; rollback plans rehearsed | ArchLead + DevOps |
| **2** | PHPStan +2 levels; syntax modernized; tests pass | TestLead |
| **3A** | Data migration scripts tested; benchmarks accept or improve | DBArch + TestLead |
| **3B** | Translation helper finalized; compatibility layer designed; pilot prep complete | ArchLead + DBArch |
| **4A** | Pilot migrations complete; parity proven; rollback tested | DBArch + TestLead |
| **4B** | Cart decomposed; services testable; integration tests lock behavior | CartLead + TestLead |
| **5A** | Module standalone + all tests pass | CartLead + TestLead |
| **5B** | Module integrated; legacy APIs work; no checkout regression | CartLead + TestLead |

---

## Rollback Checkpoints

| Checkpoint | Condition | Owner |
|------------|-----------|-------|
| **A** | After schema prep, before read switch | DBArch |
| **B** | After dual-write enablement | DBArch |
| **C** | After read path switch per domain | DBArch + DevOps |
| **D** | Before any legacy column/constraint drops | DevOps |

**Max rollback time:** < 4 hours per checkpoint.

---

## Release & Hygiene

- [ ] [S] Prepare CHANGELOG updates per phase | CartLead | Per sprint
- [ ] [S] Ensure commit messages link work items | CartLead | Per sprint
- [ ] [S] Run post-release validation checklist per cutover | TestLead | Per sprint
