# NGauge Modernization Plan

Last updated: 2026-03-09
Project: NGauge_Base (Yii2 Advanced)

## 1) Goal
Modernize a 10+ year legacy Yii2 codebase, reduce technical debt, and extract cart/order functionality into a reusable module.

## 2) Confirmed Direction

### Delivery approach
- Sequence: general cleanup first, then module extraction.
- Modernization mode: aggressive (full rewrite where needed).
- Cart module package/name: `portalpeople/ngauge-cart`.
- Target namespace: `PortalPeople\Cart\`.

### Data modeling policy (DB vs JSON)
- Store in relational columns when data is:
  - frequently filtered/sorted/joined,
  - financial/transactional,
  - needed for reporting and indexing.
- Store in JSON when data is:
  - integration-specific and variable,
  - sparse/optional metadata,
  - not commonly queried.
- Use hybrid (JSON + generated/indexed columns) for fields inside JSON that must be queried at speed.

### Multi-language policy
- Move from composite identity (`id + language`) toward single identity (`id`) with translation storage.
- Use phased migration with compatibility layer and dual-write before removing legacy language-key assumptions.
- Pilot low-risk reference tables first.

## 3) Current Findings Summary
- Legacy syntax and style inconsistencies across models/controllers/views.
- Significant duplication patterns in extended/data/search model structures.
- Cart domain is high complexity and tightly coupled.
- Broad use of `language` in identity, relations, search models, and controller `findModel` signatures.

## 4) Target Architecture

### 4.1 Domain structure
- Thin controllers.
- Business rules in services.
- Models focused on persistence and validation.
- Shared cross-domain logic moved into reusable modules.

### 4.2 Cart domain target
- Module: `portalpeople/ngauge-cart`.
- Core model/service split:
  - Models: Cart, CartLine, Order, Quote.
  - Services: CartService, PricingService, ShippingService, OrderService.
- Backward compatibility via temporary facades in NGauge_Base.

### 4.3 Translation target
- Primary row by `id` only.
- Translation payload for translatable fields in structured JSON.
- Optional generated/indexed columns for high-read translations where needed.
- Language fallback strategy (requested language -> default language).

## 5) Phased Roadmap

## Phase 0 — Readiness and Baseline
Objective
- Establish safety rails before structural refactors.

Outputs
- Baseline static analysis and test status.
- Inventory of multi-language touchpoints and composite key dependencies.
- Migration dependency map for cart and translations.

Exit criteria
- Baseline captured and reproducible.
- High-risk areas explicitly listed with owners.

## Phase 1 — Foundation Cleanup
Objective
- Remove high-noise legacy patterns and standardize code style.

Outputs
- Legacy syntax modernization (array syntax/control structure style where applicable).
- Deprecated component migration plan enacted for critical paths.
- Initial typing hardening in key models/services.

Exit criteria
- Core domains compile and pass baseline checks after syntax modernization.

## Phase 2 — Data Structure Optimization
Objective
- Align storage with access patterns for performance and maintainability.

Outputs
- Critical JSON fields moved to relational columns where required.
- Generated/indexed columns introduced for queried JSON fields.
- Product/SEO and cart field placement decisions implemented.

Exit criteria
- No slow critical paths depending on heavy JSON extraction for core queries.

## Phase 2.5 — Multi-language Refactor Track
Objective
- Transition from `id + language` identity patterns to translation storage while preserving behavior.

Outputs
- Compatibility layer supporting legacy contracts during migration.
- Pilot migration on low-risk table(s), then medium-risk domains.
- Search/relation/controller rewrites away from language-as-identity assumptions.

Pilot candidates
- First: `sys_country`
- Next: `realexcodes` or `sys_errors`

Risk tiers
- Low: reference/system tables.
- Medium: content/catalog tables.
- High: transactional and financial domains.

Exit criteria
- Pilot CRUD/search parity proven.
- Legacy language query contracts still resolve through compatibility layer.

## Phase 3 — Cart Domain Refactor In-Place
Objective
- Reduce cart complexity before extraction.

Outputs
- Decompose oversized cart model/controller logic.
- Move business logic to dedicated services.
- Consolidate duplicate/extended cart structures.

Exit criteria
- Cart logic is modular, testable, and ready for package extraction.

## Phase 4 — Module Extraction (`portalpeople/ngauge-cart`)
Objective
- Build reusable cart module using NGauge module conventions.

Outputs
- New module scaffold with composer package metadata and PSR-4 autoloading.
- Migrated models/services/controllers/views.
- Module-level tests and configuration.

Exit criteria
- Module can be installed and run in NGauge_Base without functional regression.

## Phase 5 — Integration and Backward Compatibility
Objective
- Introduce module into NGauge_Base with controlled migration path.

Outputs
- Composer/config integration.
- Facade/adapters for legacy class and route compatibility.
- Incremental call-site migration.

Exit criteria
- Existing flows run against module implementation transparently.

## Phase 6 — Broader Consolidation
Objective
- Standardize reusable base patterns and reduce code duplication.

Outputs
- Unified base model/search patterns where justified.
- Reduced duplicated extended/data/search structures.
- Cleaner separation between domain code and infrastructure concerns.

Exit criteria
- Measurable reduction in duplicate structures and maintenance hotspots.

## Phase 7 — Additional Modularization
Objective
- Extract other suitable domains after cart success.

Candidate domains
- Products
- Accounts/users
- Shipping/delivery

Exit criteria
- Repeatable extraction playbook proven by at least one additional domain.

## 6) Compatibility and Rollback Strategy
- Use per-phase cutover checkpoints:
  1. schema prepared,
  2. dual-write enabled,
  3. read path switched,
  4. legacy cleanup delayed until stability window passes.
- Keep rollbacks simple:
  - toggle reads back to legacy path,
  - retain reversible migrations during validation windows,
  - snapshot before each high-risk cutover.

## 7) Success Metrics
- Reduced controller/model complexity in cart domain.
- Faster key list/search pages with fewer JSON extraction bottlenecks.
- Elimination of language-as-primary-identity in migrated tables.
- Stable checkout/payment/shipping outcomes in high-risk domains.
- Lower duplication and clearer module boundaries.

## 8) Out of Scope (for this plan)
- Full Yii3 migration.
- Immediate rewrite of all modules in one pass.
- Dropping legacy compatibility layers before stability criteria are met.
