Cube 2.0 Migration Roadmap#

The plan for moving Manex’s ERP off .NET Framework 4.8 / EF6 / WinForms / classic ASP.NET onto .NET 8 / EF Core 8 / ASP.NET Core 8 REST APIs.

From: .NET Framework 4.8/4.0 monolith (EF6, MVC/WebForms, WinForms/WPF, Windows Service) To: .NET 8 modular monolith — ASP.NET Core 8 REST APIs + EF Core 8, container-first, web-first UI.

Status snapshot#

Ground rules#

These apply to every phase.

Architecture#

• API-first — business logic lives behind versioned REST endpoints (/api/v1/...); no direct DB calls from UIs.
• Database-first EF Core — models scaffolded from the existing MSSQL baseline; schema evolves via EF migrations.
• Unified auth — every module authenticates and authorizes through the central Auth API from Phase 0.
• Modular monolith — one solution, bounded contexts by folder, not by service. See ADR 0002.

Code#

• Modern .NET only — async/await, DI, appsettings.json, nullable enabled, minimal APIs / middleware. No System.Web.
• Consistent API design — versioned endpoints, ApiResponse<T> envelope, ProblemDetails for errors, no leaked stack traces.
• Centralized ILogger with correlation IDs (Serilog + X-Correlation-ID).

Migration process#

• Phase 0 before all — no feature migrated until foundation (auth, permissions, CI/CD) is stable.
• Parallel operation — old and new systems can run side-by-side via feature flags.
• Refactor, don’t copy — business logic is adapted for maintainability and performance, not blindly ported.

Testing & quality#

• Unit + integration tests required for every new API.
• Regression testing against legacy — outputs must match unless explicitly improved and signed off.
• No go-live without UAT.

Data & integration#

• No direct DB writes outside API’s DbContext / DAO layer.
• Schema changes are versioned via EF migrations.
• Migration scripts validated before production loads.

Cross-cutting workstreams#

Run alongside the phase work.

Authentication integration#

Every migrated module must consume the Phase 0 JWT auth API. Roles / claims are mapped from AspMnxGroup → JWT role + perm claims (see ADR 0001).

Data synchronization layer#

While parts of the system are still legacy, an API Sync Layer keeps the legacy DB and the new one aligned. This is a full workstream in its own right — change data capture, idempotent writes, reconciliation reports, cutover playbook per module.

Rollback plans#

Each phase defines abort criteria and a rollback path. Feature flags gate cutover so we can revert cleanly.

Non-functional targets#

Per-endpoint SLOs, load-test baselines, error-budget policy — captured at the start of each phase.

AI-assisted development#

The team uses Windsurf and Cursor for AI-assisted coding. The Copilot instructions tell agents where things live and what patterns to follow. Ground rules for AI contributions:

1. Value good reasoning over authority — arguments backed by logic, evidence, or design rationale.
2. Novel tech is allowed if it improves scalability, maintainability, or delivery speed.
3. Speculative ideas are marked [Speculative] so the team can weigh risk.
4. Challenge conventional wisdom — assess on technical merit.
5. Evidence > opinion.