@multisystemsuite/create-mf-app 1.0.11 → 1.0.14

package/README.md

@@ -2,6 +2,8 @@
 
 **`@multisystemsuite/create-mf-app`** — TypeScript CLI that scaffolds production-grade **enterprise microfrontend platforms** using React 19, Vite 7, Module Federation, React Router, Material UI, Docker, and npm workspaces.
 
+Includes **10+ architect-level pillars** — security, observability, scalability, failure recovery, folder structure, CI/CD, accessibility, DX, and a capstone architect guide with audit scripts for every pillar.
+
 Inspired by **Module Federation** — optimized for React microfrontends, Vite, runtime federation, SaaS dashboards, and internal developer platforms.
 
 ---
@@ -15,12 +17,14 @@ Inspired by **Module Federation** — optimized for React microfrontends, Vite,
 - [CLI reference (create-mf-app)](#cli-reference-create-mf-app)
 - [Custom child & shared app names](#custom-child--shared-app-names)
 - [Enterprise platform flags](#enterprise-platform-flags)
+- [Enterprise architect pillars](#enterprise-architect-pillars)
 - [Generated monorepo structure](#generated-monorepo-structure)
 - [Infrastructure & deployment (parent workspaces)](#infrastructure--deployment-parent-workspaces)
 - [MF Platform CLI (inside generated projects)](#mf-platform-cli-inside-generated-projects)
 - [Using corelib (shared library)](#using-corelib-shared-library)
 - [Enterprise design system & theming](#enterprise-design-system--theming)
 - [Module Federation](#module-federation)
+- [Performance & federation architecture](#performance--federation-architecture)
 - [SDK packages](#sdk-packages)
 - [Task runner & build cache](#task-runner--build-cache)
 - [Plugins & devtools](#plugins--devtools)
@@ -57,6 +61,7 @@ npx create-mf-app my-platform --type=parent --children=billing,orders --shared=c
 npm run build
 node dist/index.js my-platform --control-plane -y
 node dist/index.js my-platform --type=parent --children=admin,billing --shared=corelib -y
+node dist/index.js add-child analytics --cwd=./my-platform --port=4205 -y
 ```
 
 **Global install** (optional):
@@ -108,10 +113,11 @@ Then use the scripts in [How to use the generated project](#how-to-use-the-gener
 - **`task-runner/`** — parallel builds + hash cache (`.mf/cache`)
 - **`plugins/`** — React, Vite, Federation, MUI, Auth, Charts, Workflow, Monitoring
 - **`devtools/`** — federation inspector, profiler, theme inspector
-- **`runtime-config/`** — tenant configs, remote manifests, feature flags
+- **`runtime-config/`** — tenant configs, remote manifests, pillar configs (scaling, resilience, structure, observability, architect roadmap)
 - **`templates/`** — LIMS, ERP, HMS, SaaS enterprise blueprints
 - **`ai/`** — AI-ready prompt engine + semantic search hooks
 - **`governance/`** — import boundaries, CODEOWNERS, dependency rules
+- **Enterprise pillar docs + audits** — security, DX, observability, a11y, CI/CD, scalability, failure recovery, folder structure, architect capstone
 - **CI/CD** — GitHub Actions, GitLab CI, Helm chart
 - Root scripts for dev, watch, preview, release, affected builds, **per-child dev shortcuts**
 
@@ -181,6 +187,7 @@ npm run local        # build all apps → watch → preview all ports → live-r
 | Command | When to use |
 |---------|-------------|
 | `npm run local` | **Default daily dev** — all apps (main + every child + shared lib) |
+| `npm run local:fast` | Smart build (skip unchanged) + watch + preview — faster iteration |
 | `npm run dev` | Print env + run each app's Vite dev server (no federation build watch) |
 | `npm run dev:fast` | Dev build once, then preview + live-reload |
 | `npm run dev:safe` | Production build, then preview only |
@@ -251,11 +258,24 @@ npm run release:major
 
 ### Add a new remote after scaffold
 
-Use the built-in MF CLI (recommended):
+**Recommended — use `create-mf-app add-child`** (fully wires federation, host routes, `mf.json`, env ports, and npm scripts):
+
+```bash
+npx create-mf-app add-child analytics --cwd=./my-platform --port=4205 -y
+```
+
+From the CLI repo during development:
+
+```bash
+node dist/index.js add-child analytics --cwd=./mf-structure-test --port=4205 -y
+```
+
+This scaffolds `apps/analytics/`, updates the host router (`/analytics/*`), corelib registries, `remote-manifest.json`, root `package.json` scripts (`npm run analytics`), and `.env` port entries — the same wiring as children created at initial scaffold time.
+
+**Alternative — MF CLI inside the monorepo** (minimal scaffold; manual federation wiring may still be needed):
 
 ```bash
 npm run mf -- generate app inventory
-# wires federation, port, mf.json, and npm scripts
 ```
 
 Or copy an existing child app folder and update `mf.json`, `federation.config.ts`, host routes, and root `package.json` scripts manually.
@@ -264,6 +284,8 @@ Or copy an existing child app folder and update `mf.json`, `federation.config.ts
 
 ## CLI reference (create-mf-app)
 
+### Create a new project
+
 ```bash
 npx create-mf-app <project-name> [options]
 ```
@@ -284,6 +306,45 @@ npx create-mf-app <project-name> [options]
 | `-y`, `--yes` | Non-interactive (use defaults where applicable) |
 | `-h`, `--help` | Show help |
 
+### Add a child to an existing parent workspace
+
+```bash
+npx create-mf-app add-child <child-name> --cwd=./my-platform [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--cwd=./my-platform` | Parent monorepo root (must contain `mf.json`; default: current directory) |
+| `--port=4205` | Dev/preview port for the new remote (default: next free port after existing apps) |
+| `-y`, `--yes` | Non-interactive |
+| `-h`, `--help` | Show add-child help |
+
+**Example:**
+
+```bash
+npx create-mf-app add-child analytics --cwd=./my-platform --port=4205 -y
+cd my-platform
+npm run analytics
+```
+
+**What gets updated:**
+
+- `apps/<child-name>/` — full enterprise child remote scaffold
+- `mf.json` — project registry + federation remotes
+- `apps/main` — host routes, federation config, remote type declarations
+- `apps/corelib` — permission/module/feature registries, sidebar menu
+- `runtime-config/remote-manifest.json` — remote entry map
+- Root `package.json` — `npm run <child>`, watch/preview/build scripts
+- `.env` / env variants — port and remoteEntry URLs
+- `docker-compose.yml` and `infrastructure/` — when present in the workspace
+
+**Rules:**
+
+- Workspace must be an existing **parent monorepo** with `mf.json`
+- Child name: letters, numbers, dashes only (`^[a-z0-9-]+$`)
+- Do not use `main` or the shared lib name (e.g. `corelib`)
+- Child must not already exist under `apps/`
+
 **Parent mode rules:**
 
 - `main` is **always** created as the host — never pass it in `--children` or `--shared`
@@ -462,9 +523,170 @@ See generated `docs/FEDERATION_OS.md` for full architecture.
 | Federation registry | `apps/corelib/src/federation/` |
 | Command palette | `apps/corelib/src/command-palette/` (Ctrl+K) |
 | Production hardening | `apps/corelib/src/production/` (CSP, env validation, diagnostics) |
+| React architecture | `apps/corelib/src/architecture/` + `docs/REACT_ARCHITECTURE.md` |
+| Security hardening | `apps/corelib/src/security/` + `docs/FRONTEND_SECURITY.md` |
+| Observability | `apps/corelib/src/monitoring/`, `observability/` + `docs/OBSERVABILITY.md` |
+| Accessibility | `apps/corelib/src/accessibility/` + `docs/ACCESSIBILITY.md` |
+| Release engineering | `apps/corelib/src/release/` + `docs/CICD_RELEASE_ENGINEERING.md` |
+| Scalability | `apps/corelib/src/scalability/` + `docs/ENTERPRISE_SCALABILITY.md` |
+| Failure recovery | `apps/corelib/src/resilience/` + `docs/FAILURE_RECOVERY.md` |
+| Folder structure | `apps/corelib/src/structure/` + `docs/ENTERPRISE_FOLDER_STRUCTURE.md` |
+| Architect capstone | `apps/corelib/src/architect/` + `docs/ARCHITECT_LEVEL_GUIDE.md` |
 | MF Platform CLI | `tools/mf-cli/` |
 | Project graph | `tools/project-graph/` |
 | Task runner + cache | `task-runner/` + `.mf/cache` |
+| Smart build | `smart-build.js` — dependency-order parallel builds |
+| Developer experience | `docs/DEVELOPER_EXPERIENCE.md`, `turbo.json`, root `tsconfig.json` refs |
+
+---
+
+## Enterprise architect pillars
+
+Every **federated parent workspace** ships a full **architect-level** toolkit — docs, audit scripts, corelib modules, and runtime configs. Run the **capstone audit** first, then drill into individual pillars.
+
+### Capstone — start here
+
+```bash
+npm run architect-level:audit
+```
+
+| Artifact | Purpose |
+|----------|---------|
+| `docs/ARCHITECT_LEVEL_GUIDE.md` | Synthesizes all pillars — act as Senior Frontend Architect, Performance Engineer, Platform Engineer, Enterprise UI Architect, Microfrontend Specialist, DevOps-aware Frontend Engineer |
+| `runtime-config/architect-roadmap.json` | Phased roadmap: Foundation → Hardening → Scale → Platform → Optimize |
+| `apps/corelib/src/architect/` | Capstone checklist + domain definitions |
+
+### All enterprise pillar audits
+
+| Pillar | Audit command | Documentation |
+|--------|---------------|---------------|
+| **Architect capstone** | `npm run architect-level:audit` | `docs/ARCHITECT_LEVEL_GUIDE.md` |
+| **Folder structure** | `npm run folder-structure:audit` | `docs/ENTERPRISE_FOLDER_STRUCTURE.md` |
+| **React architecture** | `npm run react:architecture-audit` | `docs/REACT_ARCHITECTURE.md` |
+| **Security hardening** | `npm run security:hardening-audit` | `docs/FRONTEND_SECURITY.md` |
+| **Developer experience** | `npm run dx:audit` | `docs/DEVELOPER_EXPERIENCE.md` |
+| **Observability** | `npm run observability:audit` | `docs/OBSERVABILITY.md` |
+| **Accessibility (WCAG)** | `npm run a11y:audit` | `docs/ACCESSIBILITY.md` |
+| **CI/CD + release** | `npm run cicd:audit` | `docs/CICD_RELEASE_ENGINEERING.md` |
+| **Scalability** | `npm run scalability:audit` | `docs/ENTERPRISE_SCALABILITY.md` |
+| **Failure recovery** | `npm run failure-recovery:audit` | `docs/FAILURE_RECOVERY.md` |
+| **Platform health** | `npm run mf:doctor` | `docs/ENTERPRISE_ARCHITECTURE.md` |
+| **Federation contracts** | `npm run federation:verify` | `apps/corelib/src/federation/` |
+
+`npm run mf:doctor` prints reminders for every pillar audit after scaffold.
+
+### Pillar summaries
+
+#### 1. Security hardening
+
+XSS prevention, CSP, secure token handling, refresh strategy (`--auth`), cookie flags, dependency audit, supply chain, federation remote trust, runtime script injection prevention.
+
+- **Corelib:** `src/security/frontendSecurityAudit.ts`, `src/federation/remoteTrust.ts`, `src/auth/refreshTokenStrategy.ts`
+- **Config:** hardened CSP in `src/production/csp.ts`
+- **Scripts:** `npm run security:hardening-audit`, `npm run security:audit`
+
+#### 2. Developer experience (DX)
+
+Smart parallel builds, incremental cache, live reload (SSE), affected detection, project graph.
+
+- **Root:** `smart-build.js` (topo-sort + parallel waves), `live-reload.js` (port 35729), `turbo.json`
+- **Scripts:** `npm run local:fast`, `node smart-build.js localdev --skip-unchanged`, `npm run dx:audit`
+- **CLI:** `mf cache invalidate`, `mf affected build`
+
+#### 3. Observability (`--monitoring` for full stack)
+
+Telemetry, distributed tracing, session replay, error tracking, user journey, performance budgets, RUM, OpenTelemetry.
+
+- **Corelib:** `src/monitoring/*` (frontendTelemetry, distributedTracing, sessionReplay, errorTracking, userJourney, performanceBudgets, rum, opentelemetry)
+- **Config:** `runtime-config/observability.config.json`
+- **Bootstrap:** `bootstrapObservability()` via `warmupCorelibShell()` when `--monitoring`
+- **Scripts:** `npm run observability:audit`
+
+#### 4. Accessibility (WCAG)
+
+Focus management, live announcer, contrast checks, skip links, landmarks, eslint-plugin-jsx-a11y.
+
+- **Corelib:** `src/accessibility/focusManagement.ts`, `liveAnnouncer.ts`, `contrastCheck.ts`
+- **Host:** skip link, `#main-content`, `LiveAnnouncerRegion`, `:focus-visible` CSS
+- **Scripts:** `npm run a11y:audit`
+
+#### 5. CI/CD + release engineering
+
+Parallel CI builds, incremental deploy, federation rollout order, canary, rollback, feature-flag rollouts.
+
+- **Workflows:** `mf-platform-ci.yml`, `mf-affected-deploy.yml`, `mf-canary-deploy.yml`, `mf-rollback.yml`
+- **Corelib:** `src/release/` (deploy strategy, federation rollout, rollback)
+- **Scripts:** `npm run cicd:audit`, `npm run release:plan`, `node scripts/release-deploy.js plan`
+
+#### 6. Enterprise scalability
+
+100k+ users, multi-tenant, CDN edge, runtime remote discovery, asset distribution, federation scaling, independent deployments.
+
+- **Corelib:** `src/scalability/` (multiTenant, cdnEdge, remoteDiscovery, assetDistribution, federationScaling)
+- **Config:** `runtime-config/scaling.config.json`
+- **Scripts:** `npm run scalability:audit`, `npm run mf:graph`
+
+#### 7. Production failure recovery
+
+Remote fallbacks, offline strategy, retry, circuit breakers, graceful degradation, runtime remote failure handling.
+
+- **Corelib:** `src/resilience/` (circuitBreaker, retryPolicy, offlineStrategy, remoteFailureHandler, gracefulDegradation)
+- **UI:** `FederationFallback` + `RemoteRouteBoundary` (emits `mf:remote-failure` events)
+- **Config:** `runtime-config/resilience.config.json`
+- **Federation expose:** `corelib/resilience` — `loadRemoteWithResilience()`, `installRemoteFailureListener()`
+- **Scripts:** `npm run failure-recovery:audit`
+
+#### 8. Enterprise folder structure
+
+Domain-driven frontend, feature modules, shared packages, federation boundaries, dependency isolation, plugin architecture.
+
+- **Corelib:** `src/structure/` (domainMap, boundaryRules, featureModules, dependencyIsolation, pluginArchitecture)
+- **Config:** `runtime-config/structure.config.json` — bounded context → remote map
+- **Governance:** `governance/module-boundaries.json`, `mf.json` tags
+- **Scripts:** `npm run folder-structure:audit`
+
+#### 9. React architecture
+
+State colocation, context splitting, server vs client state, feature-based layout, atomic design, smart/dumb components, Suspense/error boundaries, concurrent rendering.
+
+- **Corelib:** `src/architecture/reactArchitectureAudit.ts`
+- **Scripts:** `npm run react:architecture-audit`
+
+#### 10. Architect-level guide (capstone)
+
+Enterprise-grade architecture, production optimization, scalability, security, maintainability, developer productivity, deployment strategy, observability strategy, future scalability roadmap.
+
+- **Roles:** Senior Frontend Architect, Performance Engineer, Platform Engineer, Enterprise UI Architect, Microfrontend Specialist, DevOps-aware Frontend Engineer
+- **Roadmap:** `runtime-config/architect-roadmap.json` — 5 phases with milestones
+- **Scripts:** `npm run architect-level:audit`
+
+### Runtime configs (generated)
+
+```text
+runtime-config/
+├── remote-manifest.json      # Remote entry URLs + versions
+├── tenant-config.js          # Multi-tenant SaaS
+├── observability.config.json # Telemetry, RUM, OTel settings
+├── scaling.config.json       # 100k+ user targets, CDN, federation scaling
+├── resilience.config.json    # Retry, circuit breaker, offline policy
+├── structure.config.json     # Domain → remote bounded context map
+├── architect-roadmap.json    # Foundation → Optimize phase tracker
+├── deployment.config.json    # Rollout strategy (release engineering)
+└── feature-flags.js          # Runtime feature toggles
+```
+
+### Pre-production checklist
+
+```bash
+npm run architect-level:audit    # capstone — verifies all pillar docs/scripts
+npm run mf:doctor                # workspace health + pillar reminders
+npm run federation:verify        # remoteEntry health
+npm run folder-structure:audit   # DDD layout + import boundaries
+npm run security:hardening-audit # CSP, remote trust, auth
+npm run failure-recovery:audit   # circuit breakers + fallbacks
+npm run cicd:audit               # CI/CD + canary + rollback workflows
+npm run build                    # production build all apps
+```
 
 ---
 
@@ -504,13 +726,46 @@ my-platform/
 ├── plugins/
 ├── devtools/
 ├── runtime-config/
+│   ├── remote-manifest.json
+│   ├── observability.config.json
+│   ├── scaling.config.json
+│   ├── resilience.config.json
+│   ├── structure.config.json
+│   └── architect-roadmap.json
 ├── templates/
 ├── ai/
 ├── governance/
 ├── k8s/helm/mf-platform/
 ├── docs/
+│   ├── ENTERPRISE_ARCHITECTURE.md
+│   ├── ARCHITECT_LEVEL_GUIDE.md       # capstone architect guide
+│   ├── ENTERPRISE_FOLDER_STRUCTURE.md
+│   ├── REACT_ARCHITECTURE.md
+│   ├── FRONTEND_SECURITY.md
+│   ├── DEVELOPER_EXPERIENCE.md
+│   ├── OBSERVABILITY.md
+│   ├── ACCESSIBILITY.md
+│   ├── CICD_RELEASE_ENGINEERING.md
+│   ├── ENTERPRISE_SCALABILITY.md
+│   ├── FAILURE_RECOVERY.md
+│   └── PLATFORM_ARCHITECTURE.md
 ├── scripts/
+│   ├── architect-level-audit.js
+│   ├── folder-structure-audit.js
+│   ├── react-architecture-audit.js
+│   ├── security-hardening-audit.js
+│   ├── dx-audit.js
+│   ├── observability-audit.js
+│   ├── a11y-audit.js
+│   ├── cicd-audit.js
+│   ├── scalability-audit.js
+│   ├── failure-recovery-audit.js
+│   └── release-deploy.js
 ├── .github/workflows/
+│   ├── mf-platform-ci.yml
+│   ├── mf-affected-deploy.yml
+│   ├── mf-canary-deploy.yml
+│   └── mf-rollback.yml
 ├── docker-compose.yml
 ├── .env, .env.dev, .env.staging, .env.uat, .env.prod
 ├── live-reload.js
@@ -611,7 +866,7 @@ node tools/mf-cli/bin/mf.js <command>
 | `mf federation doctor` | Check host/remotes/shared lib wiring |
 | `mf federation graph` | Export federation dependency graph |
 | `mf federation sync` | Sync remote manifests from `mf.json` |
-| `mf doctor` | Workspace health (circular deps, boundaries, mf.json, architecture protection) |
+| `mf doctor` | Workspace health (circular deps, boundaries, mf.json, architecture protection, **pillar audit reminders**) |
 | `npm run federation:verify` | HEAD-check remoteEntry URLs (`MF_REMOTES` env) |
 
 ### Architecture protection (`mss-mf`)
@@ -662,43 +917,43 @@ Emergency architect override: `MSS_PROTECT_OVERRIDE=1 mss-mf delete <path> --arc
 
 **corelib** (or your `--shared` name) is a **Module Federation remote** that exposes shared UI, config, and RBAC. Child remotes and the host import it at runtime.
 
-### Host (`apps/main`) — wrap shell with providers
+### Host (`apps/main`) — single `HostShell` expose
+
+The host uses a **CSS-only boot shell** (~137 KB gzip) and loads the MUI/RBAC shell from corelib in **one federation request** via `corelib/HostShell`:
 
 ```tsx
-const AppConfigProvider = React.lazy(() => import("corelib/AppConfigProvider"));
-const AppNavbar = React.lazy(() => import("corelib/AppNavbar"));
-const AppSidebar = React.lazy(() => import("corelib/AppSidebar"));
-const EnterpriseSidebarNav = React.lazy(() => import("corelib/EnterpriseSidebarNav"));
-const RoleProvider = React.lazy(() => import("corelib/RoleProvider"));
-const CommandPalette = React.lazy(() => import("corelib/CommandPalette"));
+const HostShell = React.lazy(() => import("corelib/HostShell"));
 
 export default function App() {
   return (
-    <React.Suspense fallback={<div>Loading…</div>}>
-      <AppConfigProvider>
-        <RoleProvider>
-          {/* navbar, sidebar, routes */}
-        </RoleProvider>
-      </AppConfigProvider>
+    <React.Suspense fallback={<ShellSkeleton />}>
+      <HostShell navLinks={<HostNavLinks />} onItemPrefetch={prefetchRemotePath}>
+        <AppRouter />
+      </HostShell>
     </React.Suspense>
   );
 }
 ```
 
-### Child remote — use shared badge, RBAC, tokens
+`main.tsx` bootstraps runtime remotes (manifest prefetch) before render:
 
 ```tsx
-const SharedBadge = React.lazy(() => import("corelib/SharedBadge"));
-const RoleProvider = React.lazy(() => import("corelib/RoleProvider"));
+await bootstrapRuntimeRemotes();
+warmupCorelibShell();
+```
+
+### Child remote — `RemoteAppShell` (skips duplicate providers)
+
+When embedded in the host, **`RoleProvider` is not mounted twice**. Standalone dev still wraps with `RoleProvider`:
+
+```tsx
+import RemoteAppShell from "corelib/RemoteAppShell";
 
 export default function App() {
   return (
-    <div className="remote-shell">
-      <RoleProvider>
-        <SharedBadge />
-        <AppRouter />
-      </RoleProvider>
-    </div>
+    <RemoteAppShell>
+      <AppRouter />
+    </RemoteAppShell>
   );
 }
 ```
@@ -708,14 +963,18 @@ export default function App() {
 | Export | Purpose |
 |--------|---------|
 | `./App` | Standalone corelib demo app |
+| `./HostShell` | **Host shell bundle** — AppConfig, RoleProvider, Navbar, Sidebar, CommandPalette |
+| `./RemoteAppShell` | **Embedded remote wrapper** — skips RoleProvider when host is active |
 | `./AppConfigProvider` | Theme + MUI provider + CSS variables |
-| `./useAppConfig` | Hook: config, palette, shell colors, toggle theme |
-| `./AppNavbar`, `./AppSidebar`, `./ThemeToggle` | Shell UI |
-| `./EnterpriseSidebarNav` | Role-filtered sidebar menu |
+| `./useAppConfig` | Combined hook (backward compatible) |
+| `./AppNavbar`, `./AppSidebar`, `./ThemeToggle` | Shell UI (also inside HostShell) |
+| `./EnterpriseSidebarNav` | Role-filtered sidebar menu + route prefetch hook |
 | `./RouteGuard`, `./RoleProvider`, `./usePermission` | RBAC |
-| `./CommandPalette` | Ctrl+K palette |
+| `./CommandPalette` | Ctrl+K palette (returns `null` when closed) |
 | `./DashboardLayout` | Dashboard shell layout |
 | `./PermissionProvider`, `./FederationFallback` | Permissions + error UI |
+| `./resilience` | Circuit breakers, retry, offline, `loadRemoteWithResilience()`, `installRemoteFailureListener()` |
+| `./ProfilerGate` | Dev-only React Profiler wrapper |
 | `./designTokens` | Token registry |
 
 ### TypeScript — add declarations in host/child
@@ -750,19 +1009,30 @@ apps/corelib/src/
 
 ### Runtime theme in your components
 
+Split config hooks reduce re-renders (prefer these over the combined hook in hot paths):
+
 ```tsx
-import { useAppConfig } from "corelib/useAppConfig";
+import {
+  useAppConfigPick,
+  useAppConfigActions,
+  useAppTheme,
+  useAppConfig, // backward compatible
+} from "corelib/useAppConfig";
 
 function MyWidget() {
-  const { config, palette, shell, toggleColorMode } = useAppConfig();
+  const { tenantId } = useAppConfigPick("tenantId");
+  const { toggleColorMode } = useAppConfigActions();
+  const { palette } = useAppTheme();
   return (
     <div style={{ color: palette.textPrimary, background: palette.surface }}>
-      {config.appName}
+      Tenant: {tenantId}
     </div>
   );
 }
 ```
 
+**Config architecture:** `AppConfigProvider` uses three contexts — **State** (config object), **Actions** (stable mutations), **Theme** (resolved palette). Sidebar/nav components use CSS variables (`--ds-*`) where possible.
+
 **Features:**
 
 - Enterprise-light / enterprise-dark presets + Azure, Atlassian, Linear-dark, etc.
@@ -784,38 +1054,41 @@ Then hard-refresh the browser.
 
 ## Module Federation
 
-### Architecture
+### Architecture (tiered host / shared / remotes)
 
 ```text
-┌─────────────────────────────────────────────────────────┐
-│  apps/main (host) :3000                                  │
-│  ├── loads corelib remote (shared UI, theme, RBAC)       │
-│  ├── loads billing remote on /billing/*                  │
-│  └── loads orders remote on /orders/*                    │
-└─────────────────────────────────────────────────────────┘
-         │ shared singletons: react, react-dom, MUI, …
+┌──────────────────────────────────────────────────────────────┐
+│  apps/main (host) :3000  — CSS shell ~137 KB gzip             │
+│  ├── eager shared: react, react-dom only                      │
+│  ├── lazy shared: react-router-dom, @tanstack/react-query     │
+│  ├── corelib/HostShell (single federation expose)             │
+│  └── feature remotes on /admin-app/*, /analytics-app/*, …     │
+└──────────────────────────────────────────────────────────────┘
+         │
          ▼
-┌──────────────┐  ┌──────────────┐  ┌──────────────┐
-│ apps/billing │  │ apps/orders  │  │ apps/corelib │
-│   :3001      │  │   :3002      │  │   :3003      │
-└──────────────┘  └──────────────┘  └──────────────┘
+┌──────────────────┐     ┌─────────────────────────────────────┐
+│  apps/corelib    │     │  apps/<child> (feature remotes)      │
+│  MUI, RBAC, DS   │◀────│  RemoteAppShell when embedded        │
+│  :3006           │     │  standard / control-plane share tiers│
+└──────────────────┘     └─────────────────────────────────────┘
 ```
 
-### Shared dependency rules (important)
+Shared policy lives in **`packages/shared-config/src/federationShared.ts`**:
 
-The generator configures federation so **one React/MUI instance** is shared:
+| Tier | Packages | Host | corelib / remotes |
+|------|----------|------|-------------------|
+| 0 | `react`, `react-dom` | eager singleton | singleton |
+| 1 | `react-router-dom`, `@tanstack/react-query` | lazy shared | shared |
+| 2 | MUI, Emotion | **not on host** | corelib + remotes |
+| 3 | `zustand`, `@xyflow/react`, … | per-app only | control-plane remotes |
 
-**Host (`apps/main/federation.config.ts`):**
+**Production:** `strictVersion: true` is enabled automatically for `prod`, `staging`, and `uat` builds (or set `VITE_MF_STRICT_SHARED=1`).
 
-- Provides shared deps with **exact semver** keys: `version: "19.0.0"` (not `^19.0.0`)
-- `singleton: true`, `import: true`
+**Remote URLs:** env-driven via `packages/shared-config/src/federationRemotes.ts` (`VITE_<APP>_REMOTE_ENTRY`). Local default:
 
-**Remotes (children + corelib):**
-
-- Consume host share scope: `requiredVersion: "^19.0.0"`
-- `singleton: true`
-
-**Shared packages:** `react`, `react-dom`, `react-router-dom`, `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`, `@mui/x-data-grid`
+```text
+http://localhost:<port>/assets/remoteEntry.js
+```
 
 **After changing federation config:**
 
@@ -826,15 +1099,66 @@ npm run local          # restart
 
 Use **hoisted install** (generated `.npmrc`: `install-strategy=hoisted`).
 
-### Remote URLs (local dev)
+---
 
-Each app's `federation.config.ts` points to:
+## Performance & federation architecture
 
-```text
-http://localhost:<port>/assets/remoteEntry.js
+Enterprise parent workspaces (and the reference **`my-platform/`** in this repo) include the optimizations below. Generated scaffolds follow the same patterns via `apps/vite.config.base.ts`, `federationShared.ts`, and corelib shell modules.
+
+### Bundle size & Vite
+
+| Feature | Location | Purpose |
+|---------|----------|---------|
+| Shared Vite base | `apps/vite.config.base.ts` | `mfSafeManualChunks`, `resolve.dedupe`, gzip/brotli in prod |
+| Host thin shell | `apps/main` | No MUI/Emotion on host boot path |
+| Lazy DataGrid | `corelib/AppDataGrid` | `@mui/x-data-grid` dynamic import |
+| Route prefetch | `main/src/routes/remoteLoaders.ts` | Hover/focus prefetch before navigation |
+| `RemoteSkeleton` | `main/src/components/RemoteSkeleton.tsx` | Non-blocking loading UI |
+
+Run bundle analysis:
+
+```bash
+npm run analyze:bundle
+# or per app: cd apps/main && npm run analyze
 ```
 
-Match ports from root `.env` when customizing.
+### Runtime remote loading
+
+| Feature | Location | Purpose |
+|---------|----------|---------|
+| Runtime manifest | `runtime-config/remote-manifest.json` | CDN/prod remote entry map |
+| Bootstrap | `main/src/module-federation/bootstrapRemotes.ts` | Fetch manifest, preconnect, prefetch `remoteEntry` |
+| Dev manifest server | `apps/main/vite.config.ts` | Serves `/runtime-config/*` in local dev |
+| Idle warm-up | `warmupCorelibShell()` in `main.tsx` | Idle-import `corelib/HostShell` |
+| Error boundaries | `main/src/components/RemoteRouteBoundary.tsx` | Per-remote fallback + retry |
+| nginx caching | `infrastructure/nginx/conf.d/federation.conf` | Short cache on `remoteEntry`, manifest at `/runtime-config/` |
+
+Env override for manifest URL:
+
+```bash
+VITE_REMOTE_MANIFEST_URL=/runtime-config/remote-manifest.json
+```
+
+### Re-render performance (corelib)
+
+- **Split contexts:** `useAppConfigState`, `useAppConfigActions`, `useAppTheme`, `useAppConfigPick`
+- **Memo shell:** `EnterpriseSidebarNav`, `AppTable`, `AppDataGrid`, host nav links
+- **Command palette:** no render when closed
+- **Control plane dashboard:** tab-isolated data (health WebSocket only in Monitor tab)
+- **Dev profiling:** `ProfilerGate` wraps host navbar, sidebar, and router regions
+
+### Host / remote communication
+
+| Channel | Mechanism |
+|---------|-----------|
+| Navigation | Host owns `BrowserRouter`; remotes use nested `<Routes>` |
+| Server state | Singleton `@my-platform/query-client` at host |
+| Theme / RBAC | corelib contexts via `HostShell` (single provider tree) |
+| Cross-MFE events | Extend with event bus / shared query keys as needed |
+
+### Reference platform
+
+The **`my-platform/`** directory in this repository is a fully wired reference implementation with all of the above. See [`my-platform/README.md`](my-platform/README.md) for app ports, scripts, and platform-specific notes.
 
 ---
 
@@ -886,10 +1210,27 @@ task-runner/
 
 ```text
 runtime-config/
-├── tenant-config.js     # Multi-tenant SaaS configs
-├── manifest-loader.js   # CDN remote manifest fetch
-├── feature-flags.js     # Runtime feature toggles
-└── branding.js          # Dynamic logo/colors injection
+├── remote-manifest.json      # Remote entry URLs + versions (host bootstrap)
+├── tenant-config.js          # Multi-tenant SaaS configs
+├── observability.config.json # Telemetry, RUM, OTel settings
+├── scaling.config.json       # Scalability targets, CDN, multi-tenant
+├── resilience.config.json    # Retry, circuit breaker, offline policy
+├── structure.config.json     # Domain → remote bounded context map
+├── architect-roadmap.json    # Foundation → Optimize phase tracker
+├── deployment.config.json    # Rollout strategy (release engineering)
+├── manifest-loader.js        # CDN remote manifest fetch
+├── feature-flags.js          # Runtime feature toggles
+└── branding.js               # Dynamic logo/colors injection
+```
+
+The host loads `remote-manifest.json` at startup (`bootstrapRuntimeRemotes`) to preconnect and prefetch `remoteEntry.js` files. In production, nginx serves `/runtime-config/` with short cache headers (`max-age=30`, stale-while-revalidate).
+
+Per-remote env overrides (build time):
+
+```bash
+VITE_CORELIB_REMOTE_ENTRY=http://localhost:3006/assets/remoteEntry.js
+VITE_ADMIN_APP_REMOTE_ENTRY=http://localhost:3001/assets/remoteEntry.js
+# … see packages/shared-config/src/federationRemotes.ts
 ```
 
 ---
@@ -914,8 +1255,10 @@ Enterprise blueprints in `templates/`:
 
 **GitHub Actions:**
 
-- `.github/workflows/mf-platform-ci.yml` — doctor, affected lint/test/build, security audit
+- `.github/workflows/mf-platform-ci.yml` — doctor, affected lint/test/build, security audit, pillar audits
 - `.github/workflows/mf-affected-deploy.yml` — affected deploy on main
+- `.github/workflows/mf-canary-deploy.yml` — canary promotion with health checks
+- `.github/workflows/mf-rollback.yml` — federation rollback workflow
 
 **Also generated:**
 
@@ -948,6 +1291,16 @@ Generated parent workspaces include:
 | `npm run cleanup` | lint:fix → imports → type-check |
 | `npm run analyze:bundle` | Rollup visualizer per app |
 | `npm run security:audit` | npm audit |
+| `npm run security:hardening-audit` | Frontend security pillar audit |
+| `npm run architect-level:audit` | Capstone — verifies all enterprise pillar docs/scripts |
+| `npm run folder-structure:audit` | DDD layout, federation boundaries, dependency isolation |
+| `npm run react:architecture-audit` | React architecture pillars |
+| `npm run dx:audit` | Developer experience maturity |
+| `npm run observability:audit` | Telemetry, RUM, tracing, error tracking |
+| `npm run a11y:audit` | WCAG accessibility checklist |
+| `npm run cicd:audit` | CI/CD + release engineering |
+| `npm run scalability:audit` | 100k+ users, CDN, multi-tenant |
+| `npm run failure-recovery:audit` | Circuit breakers, retry, fallbacks |
 | `npm run production:hygiene` | Fail on console/debugger in sources |
 
 Husky: lint-staged + type-check + tests on pre-commit; lint + tests on pre-push. Commitlint for Conventional Commits.
@@ -961,6 +1314,8 @@ Husky: lint-staged + type-check + tests on pre-commit; lint + tests on pre-push.
 | Script | Purpose |
 |--------|---------|
 | `local` | **Main dev command** — build:local + watch + preview + live-reload (all apps) |
+| `local:fast` | Smart build (skip unchanged) + watch + preview + live-reload |
+| `build:local` | `node smart-build.js localdev` — parallel dependency-order build |
 | `dev` | print-env + parallel Vite dev servers |
 | `dev:watch` | Same as `local` |
 | `dev:fast` | dev build once + preview + live-reload |
@@ -972,6 +1327,17 @@ Husky: lint-staged + type-check + tests on pre-commit; lint + tests on pre-push.
 | `preview:<app>` | Vite preview for one app |
 | `release` / `release:minor` / `release:major` | Version bump + build |
 | `federation:verify` | Remote entry health check |
+| `architect-level:audit` | Capstone enterprise platform audit |
+| `folder-structure:audit` | Domain-driven folder structure audit |
+| `react:architecture-audit` | React architecture audit |
+| `security:hardening-audit` | Frontend security hardening audit |
+| `dx:audit` | Developer experience audit |
+| `observability:audit` | Observability stack audit |
+| `a11y:audit` | Accessibility (WCAG) audit |
+| `cicd:audit` | CI/CD + release engineering audit |
+| `scalability:audit` | Enterprise scalability audit |
+| `failure-recovery:audit` | Production failure recovery audit |
+| `release:plan` | Deployment rollout plan |
 | `mf`, `mf:graph`, `mf:affected`, `mf:doctor`, `mss-mf`, `mf:protect` | Platform CLI + architecture protection |
 | `infra:gateway`, `infra:deploy:{dev,qa,uat,prod}`, `infra:detect`, `infra:routing`, `infra:health` | Auto-generated reverse proxy + deployment (parent workspaces) |
 | `control-plane`, `federation-os:infra` | Control-plane API + Federation OS observability stack |
@@ -1022,8 +1388,20 @@ For container-to-container federation, replace `localhost` remote URLs with Dock
 | File | Contents |
 |------|----------|
 | `README.md` | Ports, quick start, Docker, quality scripts |
-| `docs/ENTERPRISE_ARCHITECTURE.md` | Design system, RBAC, federation, SDK, deployment |
+| `docs/ARCHITECT_LEVEL_GUIDE.md` | **Capstone** — all architect roles, 9 deliverables, master audit suite, roadmap |
+| `docs/ENTERPRISE_ARCHITECTURE.md` | Design system, RBAC, federation, SDK, deployment, all pillar links |
+| `docs/ENTERPRISE_FOLDER_STRUCTURE.md` | DDD, feature modules, packages, federation boundaries, plugins |
+| `docs/REACT_ARCHITECTURE.md` | State, context, Suspense, error boundaries, feature layout |
+| `docs/FRONTEND_SECURITY.md` | XSS, CSP, remote trust, auth, supply chain |
+| `docs/DEVELOPER_EXPERIENCE.md` | Smart build, live reload, affected builds, caching |
+| `docs/OBSERVABILITY.md` | Telemetry, tracing, RUM, session replay, OTel |
+| `docs/ACCESSIBILITY.md` | WCAG, keyboard, ARIA, focus management |
+| `docs/CICD_RELEASE_ENGINEERING.md` | Parallel CI, canary, rollback, federation rollout |
+| `docs/ENTERPRISE_SCALABILITY.md` | Multi-tenant, CDN, remote discovery, 100k+ users |
+| `docs/FAILURE_RECOVERY.md` | Circuit breakers, retry, offline, graceful degradation |
+| `docs/RUNTIME_PERFORMANCE.md` | Runtime profiler (`--monitoring`) |
 | `docs/PLATFORM_ARCHITECTURE.md` | MF CLI, graph, cache, plugins, CI/CD |
+| `docs/ARCHITECTURE_PROTECTION.md` | Protected structure, `.mss-protected.json` |
 | `docs/CONTROL_PLANE.md` | Workflow designer, monitor, registry (with `--control-plane`) |
 | `docs/FEDERATION_OS.md` | Full Federation OS architecture (with `--federation-os`) |
 | `mf.json` | Project registry, tags, federation config |
@@ -1093,6 +1471,18 @@ node dist/index.js my-platform --control-plane -y
 node dist/index.js my-platform --type=parent --children=admin,billing --shared=corelib -y
 node dist/index.js my-federation-platform --federation-os -y
 node dist/index.js test-app --type=child --port=3001 --template=tsx
+node dist/index.js add-child analytics --cwd=./mf-structure-test --port=4205 -y
+
+# patch in-repo test workspaces (mf-test-jsx, my-platform-cp) after pillar changes
+node scripts/patch-architect-level-test-repos.js
+node scripts/patch-folder-structure-test-repos.js
+node scripts/patch-failure-recovery-test-repos.js
+node scripts/patch-scalability-test-repos.js
+node scripts/patch-cicd-test-repos.js
+node scripts/patch-a11y-test-repos.js
+node scripts/patch-observability-test-repos.js
+node scripts/patch-security-test-repos.js
+node scripts/patch-dx-test-repos.js
 
 # optional: link CLI globally
 npm link
@@ -1123,8 +1513,9 @@ npm publish --access public
 | **Federation OS preset** | `--federation-os` → full runtime, governance, observability stack |
 | **Daily dev** | `npm run local` (all apps) or `npm run billing` (one module) |
 | **Shared UI / theme** | Import from `corelib/*` federation exposes |
-| **New remote** | `npm run mf -- generate app <name>` |
+| **New remote** | `npx create-mf-app add-child <name> --cwd=./my-platform` or `npm run mf -- generate app <name>` |
 | **Enterprise modules** | Flags: `--auth`, `--charts`, `--i18n`, … |
+| **Architect pillars** | 10 enterprise audits — start with `npm run architect-level:audit` |
 | **Monorepo platform** | `mf graph`, `mf affected build`, `mf doctor` |
 | **Architecture protection** | `.mss-protected.json` + `mss-mf protect` / `delete` guards |
 | **Infrastructure** | Auto `infrastructure/` — nginx, docker, k8s, SSL, env deploy scripts |