# NGauge_Base Modernization — Executive Summary

**Project:** Modernize 10+ year legacy Yii2 application (NGauge_Base)  
**Status:** Planning (Ready for intake)  
**Timeline:** 15 weeks (phases 1–7)  
**Scope:** Code quality, cart extraction, multi-language refactor  
**Owner:** ArchLead (proposed)  

---

## 1) The Problem

NGauge_Base is a decade-old Yii2 Advanced template accumulating:
- **100+ instances** of outdated PHP syntax (array(), endif, etc.)
- **50+ obsolete patterns**: redundant extended/data/search models
- **1,076-line cart model** mixing persistence, validation, business logic, and view helpers
- **30+ tables** with composite primary keys (id + language), complicating queries and relations
- **No type safety**, minimal test coverage, and scattered documentation

**Impact:** Slow feature delivery, high maintenance burden, difficult to extract reusable modules.

---

## 2) The Vision

Transform NGauge_Base into a modern, modular Yii2 application:
- **Clean architecture:** thin controllers, focused models, dedicated services
- **Type-safe:** PHP 8.5+ with full scalar/return types
- **Modular:** Extract cart → `portalpeople/ngauge-cart` reusable module
- **Performant:** data stored for query efficiency (relational vs JSON by use case)
- **Multi-lingual:** simple id-based identity with translation storage

**Outcome:** Easier to maintain, extend, test, and share components across projects.

---

## 3) Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| **Modernization aggressiveness** | Aggressive (full rewrite where needed) | 10-year debt requires bold action |
| **Cart module platform** | `portalpeople/ngauge-cart` (PortalPeople\Cart\) | Aligns with NGauge_modules conventions |
| **Storage (DB vs JSON)** | Hybrid: relational for frequent queries, JSON for integration metadata | Balances performance and flexibility |
| **Multi-language identity** | Move to single `id` + translation JSON storage | Simplifies FK, reduces duplication, enables partial translations |
| **Compatibility** | Temporary facades during migration; removed after stability window | Minimize user disruption |

---

## 4) Phases & Timeline

| Phase | Duration | Focus | Key Deliverable |
|-------|----------|-------|-----------------|
| **0** | 1 week | Baseline, risk inventory | Metrics captured, rollback plans ready |
| **1** | 2 weeks | Syntax cleanup, deprecations | Modern codebase compiles, tests pass |
| **2** | 2 weeks | Data optimization | JSON → relational migration, benchmarks |
| **2.5** | 3 weeks | Multi-language refactor | Pilot migration + compatibility layer |
| **3** | 2 weeks | Cart decomposition | Services extracted, logic modularized |
| **4** | 2 weeks | Module extraction | Module runs standalone in NGauge_Base |
| **5** | 1 week | Integration & compatibility | Legacy routes/classes work via facades |
| **6+** | Ongoing | Consolidation & additional modules | Reduce duplication, extract products/shipping |

**Total:** ~15 weeks to cart extraction + initial stabilization.

---

## 5) Resource Needs

| Role | Count | Commitment | Responsibilities |
|------|-------|-----------|------------------|
| ArchLead | 1 | Full-time | Design decisions, risk oversight, integration |
| DBArch | 1 | 50% | Data modeling, multi-language strategy, indexes |
| CartLead | 1 | Full-time | Cart decomposition, module extraction, testing |
| TestLead | 1 | 50% | Baseline/regression testing, gate validation |
| DevOps | 1 | 25% | Rollback strategy, deployment checkpoints |

---

## 6) High-Risk Areas

| Area | Risk | Mitigation |
|------|------|-----------|
| **Payment integrations** (Paypal, WorldPay, Opayo) | Regression in checkout flow | Comprehensive integration tests before cart migration |
| **Multi-language queries** in 30+ tables | Query breakage during PK switch | Dual-write compatibility layer + pilot on low-risk tables first |
| **External module integration** (Magento/NetSuite) | Cart API changes break integrations | Facade layer maintains backward compatibility |
| **Concurrent language writes** | Data corruption during transition | Read path migration only after dual-write validation |

---

## 7) Success Metrics

- ✅ Zero slow-query reports from optimized data/multi-language changes
- ✅ Cart decomposition reduces model from 1,076 to <300 lines
- ✅ Module loads and runs in production-like environment with zero regressions
- ✅ Integration tests for checkout/payment all pass
- ✅ 50%+ reduction in duplicated model/search patterns
- ✅ All migrated code passes PHPStan level 8+

---

## 8) Assumptions & Constraints

**Assumptions:**
- Team familiar with Yii2 and database migrations
- NGauge_modules conventions accepted as standard
- Existing payment processor integrations are stable and tested

**Constraints:**
- No full Yii3 migration (separate initiative)
- Backward compatibility must be maintained during migration phases
- Changes released in tested batches, not as one big bang

---

## 9) Next Steps

1. **Week of Mar 9:** ArchLead reviews and confirms resource allocation, risk register published
2. **Week of Mar 16:** Phase 0 intake (baseline capture, inventory complete)
3. **Week of Mar 23:** Phase 1 sprint begins (syntax modernization)

---

## 10) Rollback & Escape Hatches

Each phase includes:
- Pre-cutover snapshot and revert script
- Dual-write validation window before legacy cleanup
- Kill switch to toggle reads back to legacy path within 24h of go-live

**Maximum rollback time:** < 4 hours for any phase.

---

## Appendix: Detailed Documents

- [NGauge_Modernization_Plan.md](NGauge_Modernization_Plan.md) — Full phased roadmap with exit criteria
- [NGauge_Modernization_TODOs.md](NGauge_Modernization_TODOs.md) — Actionable task backlog by sprint
- [NGauge_Base/](../NGauge_Base/) — Baseline codebase assessment and findings

