@multisystemsuite/create-node-platform

Production-style npm CLI that scaffolds an enterprise Node.js npm workspaces monorepo — a complete Enterprise Backend Operating System with API gateway, microservices, runtime orchestration, governance, observability, infrastructure automation, and a canvas-based monitoring UI.

Requirements

• Node.js >= 18.18
• npm >= 7 (uses file: workspace links for maximum compatibility)

Quick start

Interactive wizard

npx @multisystemsuite/create-node-platform

Standard microservices stack

npx @multisystemsuite/create-node-platform my-app \
  --services=auth,user,lims,qc,inventory,report \
  --gateway=true \
  --database=mongodb \
  --docker=true \
  --yes

Full enterprise platform (recommended demo)

npx @multisystemsuite/create-node-platform enterprise-backend-platform \
  --enterprise=true \
  --gateway=true \
  --database=mongodb \
  --docker=true \
  --yes

cd enterprise-backend-platform
npm install
npm run build
npm run dev:platform-ui   # monitoring-service + canvas UI

Open the Enterprise Monitoring Canvas OS at http://127.0.0.1:3010

CLI flags

| Flag | Values | Description | |------|--------|-------------| | --services | auth, user, lims, qc, inventory, report, monitoring, governance, runtime-registry | Comma-separated services. Omit with --yes for gateway-only. With --enterprise=true, all services are included automatically. | | --gateway | true (default) / false | Enable API gateway | | --database | mongodb, mysql, postgresql | Primary database layer | | --template | typescript, javascript | Scaffold is TypeScript-first | | --docker | true / false | Generate Docker + Compose assets | | --enterprise | true / false | Full enterprise stack (see below) | | -y, --yes | — | Skip interactive prompts |

You cannot scaffold no gateway and no services; the CLI exits with an error.

What --enterprise=true generates

Platform capabilities

| Capability | Description | |------------|-------------| | Enterprise Backend OS | npm workspaces monorepo with ordered TypeScript builds | | API Gateway Platform | JWT, RBAC, rate limiting, proxying, Swagger aggregation, WebSocket proxy | | Microservice Runtime Engine | Service discovery, health monitoring, topology management | | Service Registry | Dynamic registration, heartbeats, environment isolation | | Monitoring Platform | Prometheus metrics, Socket.IO, live dashboards | | Monitoring Canvas OS | React Flow canvas UI — Grafana/Datadog/Lens-style (port 3010) | | Governance Platform | API policies, deployment approvals, architecture standards | | Infrastructure Generator | Nginx, Apache, Docker, K8s, Helm, multi-env Compose | | Architecture Protection | .mss-protected.json + git hook validation | | DevOps CLI | mss-node commands for generate, deploy, monitor, validate | | Observability | OpenTelemetry stubs, Prometheus, Grafana configs | | CI/CD | GitHub Actions workflows (build + deploy) | | AI Backend Assistant | Architecture analyzer in runtime/ai-assistant/ |

Generated monorepo structure

apps/                    # Applications (gateway + microservices + canvas UI)
packages/                # Shared libraries (shared-*)
runtime/                 # Runtime engine, topology, AI assistant
monitoring/              # Prometheus + Grafana configs
governance/              # API policies, approval rules
infrastructure/          # Infra documentation
nginx/                   # Reverse proxy configs (WebSocket, SSL-ready)
apache/                  # Virtual host configs
kubernetes/              # Deployments, Services, Ingress, HPA, Helm chart
compose/                 # docker-compose.dev|qa|uat|prod.yml
docker/                  # DB init scripts
cli/                     # mss-node DevOps CLI
bin/                     # mss-node entry point
scripts/                 # start-all, validate-architecture, bump-version
.github/workflows/       # CI + deploy pipelines
.mss-protected.json      # Protected architecture manifest

Generated applications (10 with --enterprise=true)

| Application | Port | Role | |-------------|------|------| | api-gateway | 3000 | JWT/RBAC, route proxying, rate limiting, Swagger | | auth-service | 3001 | Login, register, refresh tokens | | user-service | 3002 | User management | | lims-service | 3003 | LIMS domain API | | qc-service | 3004 | QC domain API | | inventory-service | 3005 | Inventory domain API | | report-service | 3006 | Reporting API | | monitoring-service | 3007 | Metrics, visualization API, Socket.IO | | governance-service | 3008 | Policies, deployment approvals | | runtime-registry-service | 3009 | Service discovery + health registry | | api-visualization | 3010 | Enterprise Monitoring Canvas OS (Vite/React) |

Default admin (auth-service): [email protected] / ChangeMe123!

Shared packages (11 with --enterprise=true)

| Package | Purpose | |---------|---------| | shared-types | User roles, JWT types, API error shapes | | shared-constants | API versioning, pagination, header names | | shared-config | Env loading, Zod base schemas | | shared-logger | Winston logging (+ OpenTelemetry stub) | | shared-utils | Common helpers, Zod utilities | | shared-auth | JWT sign/verify, RBAC middleware | | shared-middleware | Helmet, CORS, rate limit, request ID | | shared-validation | Shared Zod validation helpers | | shared-errors | AppError, NotFound, Unauthorized, etc. | | shared-events | Platform event types (service.registered, etc.) | | shared-security | Secure headers, tenant isolation, audit logging |

API Gateway platform

• Dynamic route management and service proxying
• JWT validation + RBAC authorization
• Rate limiting and request ID tracing
• Swagger UI aggregation across services
• WebSocket proxy support (monitoring-service)
• Public routes: /health, /api-docs, auth login/register/refresh

Microservice runtime engine

Located in runtime/:

• Runtime engine — service registration, topology, environment isolation
• Topology map — runtime/topology.json
• Start script — npm run runtime:start or npx mss-node runtime start
• AI assistant — architecture analysis, bottleneck detection (runtime/ai-assistant/)

Service registry (runtime-registry-service)

POST /api/registry/services
{
  "service": "inventory-service",
  "port": 3005,
  "environment": "DEV",
  "health": "healthy",
  "version": "1.0.0"
}

Features: discovery, health checks, heartbeats, environment isolation, dynamic registration.

Enterprise Monitoring Canvas OS (api-visualization)

Grafana · Datadog · Kubernetes Lens-inspired monitoring UI at http://127.0.0.1:3010

Run

npm run dev:monitoring-service    # backend + WebSocket feed
npm run dev:visualization         # canvas UI only
npm run dev:platform-ui           # both together

Canvas features

• React Flow topology canvas with zoom/pan, minimap, snap-to-grid, fullscreen
• 10 node types: Gateway, Microservice, Database, Redis, Queue, Auth, Monitoring, WebSocket, External, Load Balancer
• Glowing animated edges for live API request flows
• HTML5 canvas particle layer for request animation
• Heartbeat pulse on nodes (green = healthy, yellow = degraded, red = failed)
• Node search/filter, right-click context menus, pin services
• Multi-environment switch: DEV · QA · UAT · PROD

8 dashboard layouts

| Layout | Focus | |--------|--------| | Infrastructure | Nginx, Docker, K8s, load balancers | | Service Topology | Live microservice communication map | | API Monitoring | Routes, latency, gateway metrics | | Database | MongoDB, MySQL, PostgreSQL, Redis | | Deployment | CI/CD, containers, rollbacks | | Security | JWT flow, RBAC, blocked requests | | Runtime Health | Service heartbeats, WebSocket activity | | DevOps | Full-stack operations dashboard |

15 draggable monitoring widgets

CPU Usage · Memory Usage · API Response Time · Request Throughput · Error Rate · Database Health · DB Latency · WebSocket Activity · Queue Depth · Docker Status · K8s Pod Health · Active Users · Runtime Errors · API Gateway Status · Service Health · Deployment Activity · Redis Cache · Nginx Routes

Widgets are drag-and-resize (react-grid-layout) with layout persistence in localStorage.

Additional UI panels

• API Routes — method, path, health, auth, latency, request count
• Request Traces — distributed tracing visualization
• Error Analytics — failed requests, auth failures, runtime exceptions
• API Gateway Dashboard — routes, JWT, RBAC, rate limits
• Database Monitoring — connection pools, latency, cache hit rate
• WebSocket Monitor — live event streams
• Security Dashboard — JWT validation flow, blocked requests
• Deployment Timeline — Docker/K8s status, rollbacks
• Infrastructure View — Nginx, Apache, Docker, K8s topology
• Live Log Stream — tail logs with level filter + search
• Alert Center — info / warning / critical alerts + toast notifications

Real-time WebSocket events (monitoring-service)

topology:init · topology:update · metrics:update · request:flow · flow:highlight · error:new · log:stream · alert:new · websocket:event · deployment:status

Visualization REST API

Base: /api/monitoring/visualization/

| Endpoint | Data | |----------|------| | /topology | Live service graph | | /metrics | Platform metrics | | /routes | API route health | | /traces | Request traces | | /errors | Error analytics | | /logs | Live log stream | | /alerts | Alert history | | /gateway | Gateway dashboard | | /databases | DB health | | /websocket | WebSocket stats | | /deployments | Deployment timeline | | /security | Security events | | /infrastructure | Infra status | | /widgets | Available widget list |

Infrastructure generator

Auto-generated for every --enterprise=true project:

| Asset | Location | |-------|----------| | Nginx reverse proxy | nginx/nginx.conf, nginx/conf.d/ | | Apache virtual hosts | apache/httpd.conf | | Dockerfiles | Every apps/*/Dockerfile (multi-stage) | | Docker Compose | docker-compose.yml + compose/docker-compose.{dev,qa,uat,prod}.yml | | Kubernetes | kubernetes/ — Deployments, Services, Ingress, HPA | | Helm chart | kubernetes/helm/ | | SSL-ready configs | nginx/conf.d/ssl.conf.example, apache/vhosts/ | | Redis + observability stack | In Compose (Prometheus :9090, Grafana :3001) |

Architecture protection (.mss-protected.json)

Protects core platform folders from accidental deletion:

• apps/api-gateway, apps/api-visualization, platform services
• packages/, runtime/, monitoring/, governance/, infrastructure/

npm run validate                    # manual validation
npx mss-node validate architecture  # via DevOps CLI

Pre-commit hook runs validation automatically (.husky/pre-commit).

Governance platform (governance-service)

• API policy engine (/api/governance/policies)
• Deployment approval workflows (/api/governance/approvals)
• Architecture standards enforcement
• Service version governance

Security platform

• JWT authentication + refresh tokens
• RBAC with enterprise roles (Analyst → System Admin)
• Secure headers (Helmet), CSP, tenant isolation
• Audit logging via shared-security
• Rate limiting on gateway and services

mss-node DevOps CLI

Included in every --enterprise=true project:

npx mss-node add service <name>       # Scaffold custom service
npx mss-node generate gateway         # Regenerate gateway
npx mss-node generate docker          # Regenerate Docker assets
npx mss-node generate nginx           # Regenerate Nginx configs
npx mss-node generate apache          # Regenerate Apache configs
npx mss-node generate kubernetes      # Regenerate K8s manifests
npx mss-node validate architecture    # Validate protected structure
npx mss-node runtime start            # Start runtime orchestration
npx mss-node deploy dev|qa|uat|prod   # Deploy environment
npx mss-node monitor services         # Health check all services
npx mss-node analyze architecture     # AI architecture analysis

Environments

| Environment | Compose file | |-------------|--------------| | DEV | compose/docker-compose.dev.yml | | QA | compose/docker-compose.qa.yml | | UAT | compose/docker-compose.uat.yml | | PROD | compose/docker-compose.prod.yml |

Root env files: .env.dev, .env.qa, .env.uat, .env.prod

Deploy scripts: npm run deploy:dev, deploy:qa, deploy:uat, deploy:prod

Tech stack (generated projects)

Backend: Node.js · Express · TypeScript · npm workspaces · Socket.IO · JWT · RBAC · Swagger · Winston · Zod

Databases: MongoDB · MySQL · PostgreSQL · Redis

Infrastructure: Docker · Docker Compose · Kubernetes · Helm · Nginx · Apache

Observability: OpenTelemetry (stub) · Prometheus · Grafana · Winston logs

Canvas UI: React · Vite · React Flow · Tailwind CSS · Zustand · Framer Motion · Recharts · D3.js · react-grid-layout · Socket.IO client

Generated root scripts

| Script | Purpose | |--------|---------| | npm run build | Ordered build: packages → gateway → services → canvas UI | | npm run dev | Start all backend apps | | npm run dev:platform-ui | monitoring-service + api-visualization | | npm run dev:visualization | Canvas UI only | | npm run dev:<workspace> | Single workspace (e.g. dev:auth-service) | | npm run validate | Architecture protection validation | | npm run runtime:start | Runtime orchestration layer | | npm run monitor:services | Health check all services | | npm run deploy:dev … deploy:prod | Environment Docker Compose deploy | | npm run docker:up | Docker Compose up |

After generation

cd my-app
npm install
npm run build
npm run dev

Per-workspace scripts use file: links — running a single service still resolves shared packages from the monorepo root.

Testing

npm test                 # all unit + integration tests
npm run test:unit        # fast generator/CLI unit tests
npm run test:integration # scaffold write-to-disk tests
npm run test:watch       # watch mode

Tests live in test/:

| Folder | Purpose | |--------|---------| | test/unit/ | parseArgv, toSlug, types, collectAllFiles, root scripts | | test/integration/ | Full scaffold output written to temp directories | | test/helpers/ | Shared fixtures and temp-dir cleanup |

Uses Node.js built-in node:test runner (Node >= 18.18).

CLI development (this repo)

npm install
npm run build       # bundle to dist/
npm run dev:watch   # tsup --watch
npm run dev         # run CLI (npm run dev -- my-app -y)

| Script | Purpose | |--------|---------| | clean | Remove dist/ | | rebuild | clean + build | | pack:check | npm pack smoke check | | publish:dry | Rebuild + dry-run publish | | publish:public | Rebuild + publish to npm |

Publish:

npm run publish:public

After global install, the command on PATH is create-node-platform.

Generator layout (this repo)

src/
├── index.ts                          # CLI entry
├── cli/parseArgv.ts                  # Commander flags
├── prompts/runPrompts.ts             # Inquirer wizard
├── types.ts                          # Service registry, options
└── generators/
    ├── root.ts                       # Root package.json, env files, README
    ├── rootPackageScripts.ts         # npm scripts orchestration
    ├── sharedPackages.ts             # Core shared packages
    ├── sharedPackagesExtended.ts     # validation, errors, events, security
    ├── gateway.ts                    # API gateway app
    ├── service.ts                    # Microservice apps (auth + generic)
    ├── platformService.ts            # monitoring, governance, registry
    ├── docker.ts                     # Docker Compose
    ├── infrastructure.ts             # Nginx, Apache, K8s, Helm, Compose envs
    ├── enterprise.ts                 # .mss-protected, runtime, CI/CD, AI
    ├── monitoringVisualization.ts    # Visualization API + simulator
    ├── visualizationDashboard.ts     # React canvas UI (api-visualization)
    ├── monitoringCanvasSystem.ts     # Widgets, layouts, alerts, canvas
    └── mssNodeCli.ts                 # mss-node DevOps CLI

License

MIT