MCM-01 — MCM Nexus
Overview, personas, and architecture for MCM Nexus — the centrally-hosted customer portal, subscription lifecycle, and shared email API.
MCM-01 — MCM Nexus
Unlike every other mcm-* component, MCM Nexus is not installed per customer — it is a single, centrally-hosted portal operated by RevDau at nexus.mcm.revdau.ai (distinct from the public marketing site, mcm.revdau.ai). It is the front door for prospective and existing customers: sign up, request a trial or purchase, get a subscription activated, download the MCM installation package, and keep a deployed MCM instance upgraded — all without RevDau staff manually wiring things up for every customer. Nexus also centralises outbound email on behalf of every MCM customer, so individual MCM deployments no longer each hold their own copy of the email provider credentials.
Each user story below is a self-contained page with its own acceptance criteria, technical design, and UI changes. This page holds only what's shared across all of them: personas, overall architecture, and cross-cutting NFRs.
Personas
| Persona | Role | Primary concern |
|---|---|---|
| Nexus Admin | RevDau staff operating the Nexus console | Reviewing leads/requests, approving/rejecting them, keeping customer licenses and credentials under control |
| Customer User | The customer's own contact(s) | Signing up, raising a trial/purchase/extension request, tracking their subscription status, getting their MCM instance running |
| Org Owner | The Customer User who first signed up with their organization's email domain | Approving or rejecting teammates' requests to join their organization in Nexus |
| MCM MSP Admin | Runs their organization's own deployed MCM instance in the MSP role — not to be confused with the Nexus Admin above (RevDau staff operating Nexus itself, not a deployed MCM instance) | Keeping their team's access to MCM uninterrupted, knowing when and how to extend |
| MCM MSP User | Any user under that MCM MSP Admin's deployed instance | Being warned before, not surprised by, a subscription lockout |
| MCM App User | Machine identity — a specific deployed MCM instance, not a person | Authenticating back to Nexus to validate its subscription, fetch install/upgrade packages, and (indirectly) send email through the shared provider |
System Context
Three principal types share the one Keycloak realm, distinguished by what they can reach:
| Principal | Can log into the Nexus UI? | Can call instance-facing APIs? |
|---|---|---|
| Nexus Admin | Yes (Nexus admin console) | No |
| Customer User | Yes (customer portal) | No |
| MCM App User | No | Yes — subscription status, package download, upgrade check |
mcm-nexus/backend (Spring Boot on Java 21, Postgres/JPA) and mcm-nexus/frontend (Next.js App Router, next-auth doing a server-side Resource Owner Password Credentials exchange against Keycloak) intentionally do not depend on mcm-common-lib, since that library is MongoDB- and multi-realm-specific to per-customer MCM.
Overall Architecture
System Context above shows Nexus's own boundary in isolation. The diagram below zooms out to show the full picture: Nexus is one single, centrally-hosted service, but every customer runs their own independently-deployed MCM instance that only ever talks to Nexus through the narrow, MCM-App-credentialed instance-facing APIs (MCM-08, MCM-09, MCM-10). Nothing about one customer's instance is visible to, or shared with, another's.
- Customer A and Customer B are two unrelated customers, each running their own self-hosted MCM instance (MCM-04 / MCM-05), fully isolated from each other, each with its own
MCM_APPcredential (MCM-07). - The RevDau Shared Demo Instance is the same kind of MCM instance, just centrally operated by RevDau rather than a customer, hosting multiple Hosted-Enterprise-Demo tenants inside it. Nexus calls into it directly (to create a demo Enterprise), rather than it calling Nexus — see MCM-03.
User Stories
| Story | Summary |
|---|---|
| MCM-02 — Customer Self-Signup | Sign up for Nexus and get an instant, unsubscribed account. |
| MCM-03 — Request a Hosted Enterprise Demo | 30-day Enterprise trial inside RevDau's shared environment, with a mandatory data-sharing disclosure. |
| MCM-04 — Request a Self-Hosted MSP Demo | 30-day MSP-role trial deployed into the customer's own infrastructure. |
| MCM-05 — Request Purchase or Extension | Move from trial to paid, or extend an existing subscription. |
| MCM-06 — Nexus Admin Review, Approve, and Reject Requests | Single queue for all incoming requests, with type-specific context. |
| MCM-07 — Subscription Activation and Secure Credential Delivery | Approval activates the license and issues MCM App credentials without further manual steps. |
| MCM-08 — MCM Instance Subscription Validation | The deployed instance checks its own entitlement to run. |
| MCM-09 — Download MCM Installation Package | Authenticated, license-scoped download of the installer artefact. |
| MCM-10 — Upgrade an MCM Instance via Nexus | The instance fetches and applies upgrades through Nexus, offering a same-line patch and a newer version separately. |
| MCM-11 — Shared Email API | One place holds email provider credentials for all MCM services. |
| MCM-12 — Nexus Admin Operational Visibility | At-a-glance trial/expiry/pending-request counts and instance health. |
| MCM-29 — Organization Join Requests | An Org Owner approves or rejects teammates requesting to join via the same email domain. |
| MCM-30 — Registry Configuration for Artifact Delivery | Nexus Admin configures the Artifact Registry connection and repository path, then manually fetches available versions. |
| MCM-32 — MSP Access Restriction on Subscription Expiry | Whole-instance block on expiry, an expiry-warning banner, and a Plan Details/Extend page. |
| MCM-33 — Release Catalog and Version Approval | Nexus Admin approves each fetched MCM version per release line, and deprecates older ones once newer versions are stable. |
| MCM-40 — Nexus Admin Creates Another Nexus Admin | A Nexus Admin creates another Nexus Admin account directly from the Nexus console. |
| MCM-41 — Invite a Teammate to the Organization | An Org Owner invites a specific teammate by email, skipping the join-request/approval step. |
Cross-Cutting Non-Functional Requirements
These apply across multiple stories above; story-specific NFRs are called out on their own pages.
| ID | Requirement |
|---|---|
| NFR-01 | Instance-facing subscription/download/upgrade endpoints must be rate-limited and abuse-protected, since they are reachable from wherever a customer instance is deployed. |
| NFR-02 | No customer's data or credentials may be visible to another customer's organization (strict tenant isolation), including across the instance-facing APIs. |
| NFR-03 | All Nexus API traffic, including instance-to-Nexus calls, must be encrypted in transit (TLS 1.2+). |
| NFR-04 | All validation, download, and upgrade calls must be audit-logged (organization, timestamp, source IP) and retained for support/security investigation. |
| NFR-05 | MSP subscription enforcement must rely on the same cached, periodically-polled status MCM-08 already maintains for ordinary request handling — no new live call to Nexus on every request, and no new failure mode where a transient Nexus outage locks out a healthy, still-licensed instance. The one exception is the explicit, user-initiated "Check Again" action on the blocked screen, which calls Nexus on demand by design. |
Out of Scope
- Online payment/billing gateway integration — Purchase and Extension remain offline-approved requests.
- Multiple MCM App credentials per Organization (multi-instance-per-customer) — one credential per Organization for now; see MCM-03 and MCM-07 for how that single credential is issued.
- SMS / third-party webhook delivery for Nexus Admin or customer notifications.
- A CI/CD pipeline and environment setup are treated as delivery prerequisites for these stories, not user-facing stories themselves, and are tracked separately.
- Partial/feature-level restriction on subscription expiry — MCM-32 always blocks the entire deployed MCM instance, not individual modules.
- The existing per-Enterprise/per-module billing plan system (
BillingPlan/EnterprisePlan, the "Current Plan" tab in the Billing dashboard) — that's a separate, already-existing concept for individual tenants' module plans, untouched by MCM-32.
User Stories
User stories and acceptance criteria — functional and non-functional requirements and system behaviour specifications.
MCM-02 — Customer Self-Signup
A prospective customer signs up for MCM Nexus with a company email — becoming their organization's Owner, or requesting to join it if a teammate already signed up first.