Getting Started#

Welcome. This page orients you to Cube 2.0 — what it is, where the migration stands today, and how the codebase is organized. When you’re ready to run it, jump to Run Locally.

What is Cube 2.0?#

Cube 2.0 is the .NET 8 rewrite of Manex’s legacy ERP.

From: .NET Framework 4.8 / EF6 / MVC + WebForms / WinForms & WPF clients / Windows Service. Monolithic. Cookie auth. Web.config. SQL Server 2017 on 192.168.9.111\SQLDEV2017, database BcomMX_01_04.
To: .NET 8 modular monolith. ASP.NET Core 8 REST APIs. EF Core 8. Container-first. JWT bearer auth. appsettings.json + env vars. Same SQL Server database — we’re evolving the schema, not throwing it away.

The migration is planned in nine phases (0–8) plus a cleanup pass. Each phase ships APIs first, then clients (or their web replacements) are refactored to consume them.

Where the migration stands#

Phase	Domain	Status
0	Foundation — auth, config, health, OpenAPI, CI/CD, tests, Docker	✅ Complete
1	Core system & security (users, groups, settings, login activity)	Planned
2	Desktop modules — Sales/RMA, AP, AR, Receiving	Planned
3	Customer & Sales	Planned
4	Inventory, Warehouse, Procurement	Planned
5	Supplier & Contracts	Planned
6	Manufacturing & Engineering	Planned
7	Finance — GL, Budgeting, Bank Rec	Planned
8	Supporting — HR, PM, Quality, Analytics	Planned
Cleanup	Remove legacy, tighten security, perf pass	Planned

The full roadmap with per-phase goals, dependencies, and risks lives in Migration Roadmap.

Ground rules (they apply to every phase)#

These are enforced by CI + code review. See the ADR log for the reasoning behind each.

Architecture#

API-first — business logic lives behind versioned REST endpoints (/api/v1/...). No direct DB calls from UIs, ever.
Database-first EF Core — the legacy schema is treated as external. Migrations are forward-only deltas we author when we change the schema. We do not re-create tables that already exist in BcomMX. See ADR 0004.
Unified auth — every module authenticates and authorizes through the JWT Auth API shipped in Phase 0. See ADR 0001.
Modular monolith, not microservices. One solution, bounded contexts by folder. See ADR 0002.

Code#

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

Process#

Feature flags let old and new run side-by-side per module.
Every API needs unit + integration tests before merge.
Regression pack must match legacy output unless explicitly improved and signed off.
No go-live without UAT.

What Phase 0 shipped#

Concretely, on phase-0/foundation:

JWT Auth API — POST /api/v1/auth/login, GET /api/v1/auth/me, GET /api/v1/auth/permissions. HS256 signing key from config; RS256/KMS upgrade path.
Envelope + errors — ApiResponse<T> for successes, ProblemDetails for failures via a global exception middleware.
Observability — Serilog with correlation-ID enrichment, request logging, JSON console output, optional Seq sink.
Ops surfaces — /health (liveness), /ready (SQL check), /docs (Swagger UI with Bearer security).
Guardrails — rate limiter (fixed window per user/IP), versioned routing (/api/v{v}/...), named-origin CORS (not AllowAll).
Shared contracts — new Manex.Contracts project holds DTOs the frontend / desktop bridge can codegen against.
Data layer — single MnxEFContext (EF Core 8). Legacy DAL folders are on disk but excluded from compile; each is rehabilitated in the phase where it lands.
Testing — xUnit + FluentAssertions; three test projects (unit, EF InMemory, integration via WebApplicationFactory). 9 smoke tests.
CI/CD — GitHub Actions runs restore → build → test → docker build on every PR against develop / master.
Docker — multi-stage web image, non-root runtime, HEALTHCHECK. Compose stack with SQL Server + Seq.
Two run modes — fresh sandbox (Docker db container) or against the real legacy DB via a compose override. See Run Locally.
Docs — this Hugo site, ADRs, migration roadmap, all in-repo.

Solution layout#

src/
  Manex.Contracts/   Shared DTOs, ApiResponse<T>, versioned contracts
  Manex.Data/        MnxEFContext (EF Core 8) + entity classes
  Manex.Web/         ASP.NET Core 8 host (JWT, Serilog, health, OpenAPI)
tests/
  Manex.Web.Tests/           Unit tests
  Manex.Data.Tests/          DbContext + EF smoke (InMemory)
  Manex.IntegrationTests/    WebApplicationFactory end-to-end
build/
  Directory.Build.props      Global: net8.0, nullable, TreatWarningsAsErrors
deploy/docker/
  web.Dockerfile             Multi-stage, non-root, HEALTHCHECK
  docker-compose.yml         Sandbox mode (empty SQL Server + Seq)
  docker-compose.legacy.yml  Override for real BcomMX_01_04
docs/                        This site (Hugo)

Legacy .NET Framework 4.8 code lives under manexcloud/ and src/Manex.BLL / src/Manex.DAL. Files on disk, excluded from cube2-backend.sln, slated for removal after Phase 8.

Where to go next#

👉 Run Locally — prerequisites, first-time setup, both run modes, JWT curl example, tests, EF migrations, common issues.
Architecture — legacy solution layout and request flow, plus the ADR log.
Migration Roadmap — the full per-phase plan.
Modules — legacy business-logic reference by module (Sales, Purchasing, Inventory/SCM, Manufacturing, Financials).
Reference — glossary of acronyms and cross-cutting conventions.

Getting help#

Repo: git@bitbucket.org:MANEXaloha/cube2-backend.git
Working branch: develop
Phase-0 PR branch: phase-0/foundation (open for review)
Copilot / AI-agent guidance: .github/copilot-instructions.md at the repo root