@jeffrey2423/coding-standards 1.0.0 → 2.0.0

package/standards/{mobile-react-native-standards.md → mobile/react-native/react-native-standards.md}

@@ -1,6 +1,14 @@
+---
+title: React Native Development Standards
+platform: mobile
+track: react-native
+load_when: "Building a React Native app — Expo, Zustand, Expo Router, NativeWind."
+updated: 2026-06
+---
+
 # Mobile React Native Development Standards
 
-> **Note**: For shared architectural principles (Clean Architecture, DDD, design philosophy), refer to [architecture-patterns.md](./architecture-patterns.md). For design system (colors, typography, UX), refer to [technical-preferences-ux.md](./technical-preferences-ux.md). React Native shares the same core architecture philosophy as the frontend standards in [frontend-standards.md](./frontend-standards.md) — adapted for native mobile.
+> **Note**: For shared architectural principles (Clean Architecture, DDD), refer to [`../../core/clean-architecture-ddd.md`](../../core/clean-architecture-ddd.md). For design system (colors, typography, UX), refer to [`../../web/_base/design-system-ux.md`](../../web/_base/design-system-ux.md). React Native shares the same core architecture philosophy as the web frontend standards in [`../../web/_base/frontend-standards.md`](../../web/_base/frontend-standards.md) — adapted for native mobile.
 
 ---
 

package/standards/{technical-preferences-ux.md → web/_base/design-system-ux.md}

@@ -1,4 +1,11 @@
-# Technical Preferences - UX Configuration
+---
+title: Design System & UX
+platform: web
+load_when: "UI/visual work — colors, typography, spacing, accessibility, performance targets."
+updated: 2026-06
+---
+
+# Design System & UX
 
 ## Project Setup Configuration
 Based on Frontend Development Standards and Clean Architecture Implementation

package/standards/web/_base/frontend-architecture.md

@@ -0,0 +1,75 @@
+---
+title: Frontend Architecture
+platform: web
+load_when: "Any web work — defines folder structure, routing conventions, and how to pick a web track."
+updated: 2026-06
+---
+
+# Frontend Architecture
+
+Applies to every web track (SPA, Single-SPA, Module Federation). Implements [`core/clean-architecture-ddd.md`](../../core/clean-architecture-ddd.md) on the frontend.
+
+## Choosing a web track
+
+These are **independent options**, not a default-plus-exceptions. Pick by need:
+
+| Track | Choose when | Doc |
+|---|---|---|
+| **SPA** | One cohesive app, single deployable | [`web/spa/spa-standard.md`](../spa/spa-standard.md) |
+| **Single-SPA** | Independently-deployed modules, possibly **mixed frameworks**, hard lifecycle isolation | [`web/single-spa/single-spa-standard.md`](../single-spa/single-spa-standard.md) |
+| **Module Federation** | Homogeneous React, capabilities reused across products, **license-gated runtime composition** | [`web/microfrontends/module-federation-standard.md`](../microfrontends/module-federation-standard.md) |
+
+Default to **SPA** until a concrete need justifies microfrontend complexity. Don't adopt it speculatively.
+
+## Folder structure
+
+Organize by **business module → domain → feature**, with Clean Architecture layers inside each feature:
+
+```
+src/
+├── main.tsx                 # entry point
+├── routes/                  # TanStack Router (route definitions only)
+│   ├── __root.tsx           # root layout (providers)
+│   ├── _auth.tsx            # pathless public layout
+│   └── _app.tsx             # pathless protected layout
+├── modules/                 # business logic
+│   └── sales/               #   MODULE
+│       └── quotes/          #     DOMAIN
+│           └── cart/        #       FEATURE
+│               ├── domain/          # entities, repo interfaces, types
+│               ├── application/     # use-cases, hooks, store
+│               ├── infrastructure/  # repo impls, api, adapters
+│               └── presentation/    # components
+├── shared/                  # reusable components, hooks, lib, types
+├── app/                     # global providers + stores
+├── infrastructure/          # global services (api, storage, pwa)
+└── styles/                  # global styles
+```
+
+## TanStack Router conventions
+
+| Prefix | Effect | Example |
+|---|---|---|
+| `_` | Pathless layout (no URL segment) | `_app.tsx` |
+| `.` | Flat routing | `orders.$id.tsx` → `/orders/:id` |
+| `-` | Ignored by router (colocated files) | `-components/` |
+| `$` | Dynamic parameter | `$orderId.tsx` → `:orderId` |
+
+## Core rules
+
+- **MUST** keep `routes/` for route definitions only; business logic lives in `modules/`.
+- **MUST** split state by ownership: **Zustand** (global client) / **TanStack Query** (server) / `useState` (local).
+- **MUST** keep `routeTree.gen.ts` untouched (auto-generated).
+- **MUST** meet WCAG 2.1 AA in every component.
+- **SHOULD** lazy-load routes (automatic with TanStack Router `autoCodeSplitting`).
+- **SHOULD** build complex UI by composing small reusable components.
+
+## State management split
+
+| State | Tool | Example |
+|---|---|---|
+| Server data (fetch/cache/sync) | TanStack Query | product list, order detail |
+| Global client state | Zustand | auth session, theme, cart |
+| Local UI state | `useState`/`useReducer` | modal open, form field focus |
+
+See [`frontend-standards.md`](frontend-standards.md) for detailed component, form, and testing rules.

package/standards/{frontend-standards.md → web/_base/frontend-standards.md}

@@ -1,3 +1,10 @@
+---
+title: Frontend Development Standards
+platform: web
+load_when: "Any web UI implementation — components, hooks, forms, state, testing."
+updated: 2026-06
+---
+
 # Frontend Development Standards
 
 ## Resumen

package/standards/web/_base/technology-stack.md

@@ -0,0 +1,40 @@
+---
+title: Web Technology Stack
+platform: web
+load_when: "Any web work — the approved frontend toolchain and versions."
+updated: 2026-06
+---
+
+# Web Technology Stack
+
+The approved frontend toolchain. Use these by default; deviations need a stated reason.
+
+| Category | Technology | Version | Notes |
+|---|---|---|---|
+| Bundler | Vite | 7+ | native ESM, fast HMR |
+| Framework | React | 19 (18+ supported) | functional components + hooks |
+| Language | TypeScript | 5+ | `strict` mode mandatory |
+| Routing | TanStack Router | 1+ | file-based, type-safe, auto code-splitting |
+| Client state | Zustand | 5+ | feature-based stores |
+| Server state | TanStack Query | 5+ | cache, sync, optimistic updates |
+| UI components | shadcn/ui + Radix UI | latest | install shadcn via MCP, not by hand |
+| Styling | TailwindCSS | v4 | utility-first; design tokens from the UI kit |
+| Forms | React Hook Form + Zod | latest | schema-driven validation |
+| HTTP | Axios | latest | with interceptors |
+| Testing | Vitest + React Testing Library + MSW | latest | MSW for API mocking |
+| PWA | `vite-plugin-pwa` + Workbox | latest | offline-first where required |
+
+## Rules
+
+- **MUST** use TypeScript `strict`; no implicit `any`.
+- **MUST** validate forms with Zod schemas; never trust client input.
+- **MUST** keep the initial bundle < 500KB gzipped (see performance targets in [`design-system-ux.md`](design-system-ux.md)).
+- **SHOULD** install shadcn/ui components via the MCP integration rather than hand-copying.
+- **SHOULD** prefer TanStack Query for all server state instead of bespoke fetch-in-effect logic.
+
+## Microfrontend dependency sharing
+
+When using a microfrontend track, shared dependencies (React, router, query client, Zustand) **MUST** be declared `singleton: true` with a `requiredVersion` to prevent duplicate runtime instances. Track-specific configuration:
+
+- Module Federation → [`web/microfrontends/module-federation-standard.md`](../microfrontends/module-federation-standard.md)
+- Single-SPA → [`web/single-spa/single-spa-standard.md`](../single-spa/single-spa-standard.md)

package/standards/web/microfrontends/module-federation-standard.md

@@ -0,0 +1,216 @@
+---
+title: Module Federation Microfrontends Standard
+platform: web
+track: microfrontends
+load_when: "Building a homogeneous (all-React) multi-product web platform where capabilities are reused across products and modules are enabled/disabled per license without redeploy."
+updated: 2026-06
+---
+
+# Module Federation Microfrontends Standard
+
+> **Choose this track when** the whole frontend is a **homogeneous React stack** and you want: efficient sharing of singleton dependencies, end-to-end TypeScript typing across module boundaries, native code-splitting, and **runtime composition driven by the backend** (per-tenant licensing). If you must mix frameworks or need hard per-module lifecycle isolation, use the [Single-SPA track](../single-spa/single-spa-standard.md) instead.
+
+This standard uses **Module Federation 2.0** (`@module-federation/enhanced`), whose runtime is decoupled from the bundler into a standalone SDK. That decoupling is what makes **dynamic, license-gated remote loading** possible: the host asks the backend which remotes to load and registers them at runtime.
+
+## The two axes
+
+A multi-product platform has two **independent** dimensions. Conflating them is the classic mistake.
+
+|              | Capability 1 | Capability 2 | Capability 3 | Capability 4 |
+|--------------|:---:|:---:|:---:|:---:|
+| **Product A** | ✅ | ✅ |   |   |
+| **Product B** | ✅ |   | ✅ |   |
+| **Product C** |   | ✅ |   |   |
+| **Product D** |   |   |   | ✅ |
+
+- **Capabilities** (horizontal) = **remote MFEs**. Built, deployed and versioned independently. Written **once**, reused across products.
+- **Products** (vertical) = **router layouts inside the single shell**. They compose capabilities and pass them props. Creating a new product = adding a folder with a `route.tsx`, not a new app.
+
+## Core rules
+
+- **MUST** use a **single shell, single router, single session**. Never nest a shell inside a shell.
+- **MUST** model products as **route layouts** in the shell; model capabilities as **remote MFEs**.
+- **MUST** keep capabilities **product-agnostic**: a remote receives typed props and adapts; it never knows which product hosts it.
+- **MUST** declare shared singletons (`react`, `react-dom`, router, query client, UI kit, contracts) with `singleton: true` and a `requiredVersion`. Symmetric config between shell and every remote.
+- **MUST** decide which remotes load from a **backend manifest endpoint** keyed by tenant/license — the frontend never hardcodes that decision.
+- **MUST** guard products and capabilities with declarative two-level license guards (`beforeLoad`).
+- **MUST** version the shared `@org/contracts` package semantically; a breaking prop change is a new major.
+- **SHOULD** wrap remote loading in `Suspense` + an `ErrorBoundary` with an offline fallback (CDN failure is a real risk).
+- **SHOULD NOT** create "private" props or events the contracts package doesn't describe — that breaks parity and typing.
+
+## Stack (2026)
+
+| Concern | Choice |
+|---|---|
+| Federation | **Module Federation 2.0** — `@module-federation/enhanced` (runtime SDK + `mf-manifest.json`) |
+| Bundler | Vite 7+ (`@module-federation/vite`) or Rspack (`@module-federation/rsbuild-plugin`) |
+| Framework | React 19 + TypeScript strict |
+| Router | TanStack Router 1+ (typed nested layouts) |
+| Server state | TanStack Query 5+ (singleton) |
+| Shared packages | `@org/contracts` (types/props), `@org/ui-kit` (design system), `@org/license` (entitlements) |
+
+## Architecture in three layers
+
+```
+SHELL (single host)
+  • boots, fetches license + dynamic manifest
+  • defines product layouts, owns global routing + guards
+        │  Module Federation 2.0 runtime (registerRemotes / loadRemote)
+        ▼
+CAPABILITY MFEs (remotes, deployed independently)
+  mfe-capacidad-1   mfe-capacidad-2   mfe-capacidad-3 ...
+        │  build-time imports
+        ▼
+SHARED PACKAGES (npm, singleton at runtime)
+  @org/contracts   @org/ui-kit   @org/license
+```
+
+## Products as router layouts
+
+```tsx
+// shell/src/routes/producto-a/route.tsx
+export const Route = createFileRoute('/producto-a')({
+  beforeLoad: () => requireProduct('producto-a'),   // product-level license guard
+  component: () => (
+    <div className="producto-a-layout">
+      <ProductoAHeader />
+      <ProductoASidebar />
+      <main><Outlet /></main>                        {/* a capability renders here */}
+    </div>
+  ),
+});
+```
+
+```tsx
+// shell/src/routes/producto-a/capacidad-1.tsx
+import { loadRemote } from '@module-federation/enhanced/runtime';
+const Capacidad1 = lazy(() => loadRemote('mfe_capacidad_1/View'));
+
+export const Route = createFileRoute('/producto-a/capacidad-1')({
+  beforeLoad: () => requireFeature('capacidad-1'),   // capability-level guard
+  component: () => (
+    <Suspense fallback={<CapabilitySkeleton />}>
+      <Capacidad1 mode="producto-a" showExtraContext />
+    </Suspense>
+  ),
+});
+```
+
+The remote consumes typed props from `@org/contracts` and adapts — it has no knowledge of the host product:
+
+```tsx
+// mfe-capacidad-1/src/View.tsx
+import type { Capacidad1Props } from '@org/contracts';
+export default function View({ mode, showExtraContext, onAction }: Capacidad1Props) {
+  // same component, behavior adapts to `mode`
+}
+```
+
+## Dynamic, license-gated loading (the differentiator)
+
+On boot the shell asks the backend which remotes this tenant is licensed for, then registers them with the MF 2.0 runtime. Unlicensed bundles are **never downloaded**.
+
+```
+GET /api/mf-manifest?tenant=cliente-123
+{
+  "products":  ["producto-a", "producto-c"],
+  "features":  ["capacidad-1", "capacidad-2"],
+  "remotes": {
+    "mfe_capacidad_1": "https://cdn.org.com/cap1/2.4.1/mf-manifest.json",
+    "mfe_capacidad_2": "https://cdn.org.com/cap2/1.8.0/mf-manifest.json"
+  }
+}
+```
+
+```ts
+// shell/src/bootstrap.ts
+import { init, registerRemotes } from '@module-federation/enhanced/runtime';
+
+const manifest = await fetch(`/api/mf-manifest?tenant=${tenantId}`).then(r => r.json());
+
+init({
+  name: 'shell',
+  remotes: [],
+  shared: {
+    react: { singleton: true, requiredVersion: '^19.0.0' },
+    'react-dom': { singleton: true, requiredVersion: '^19.0.0' },
+  },
+});
+
+registerRemotes(
+  Object.entries(manifest.remotes).map(([name, entry]) => ({ name, entry })),
+);
+```
+
+**Commercial implication:** selling a new module to a tenant = flipping a backend flag. The next session's manifest includes the remote and the UI exposes it. **No redeploy, no client update.**
+
+## Static shell config (build-time remotes that are always present)
+
+```ts
+// shell/vite.config.ts
+import { federation } from '@module-federation/vite';
+export default defineConfig({
+  plugins: [react(), federation({
+    name: 'shell',
+    remotes: {
+      mfe_capacidad_1: 'mfe_capacidad_1@/remotes/cap1/mf-manifest.json',
+    },
+    shared: {
+      react:                    { singleton: true, requiredVersion: '^19.0.0' },
+      'react-dom':              { singleton: true, requiredVersion: '^19.0.0' },
+      '@tanstack/react-router': { singleton: true },
+      '@tanstack/react-query':  { singleton: true },
+      '@org/ui-kit':            { singleton: true },
+      '@org/contracts':         { singleton: true },
+    },
+  })],
+});
+```
+
+Remote config exposes its view and **mirrors** the `shared` block (must be symmetric, or dependencies duplicate at runtime):
+
+```ts
+// mfe-capacidad-1/vite.config.ts
+federation({
+  name: 'mfe_capacidad_1',
+  filename: 'remoteEntry.js',
+  exposes: { './View': './src/View.tsx' },
+  shared: { /* same singleton block as the shell */ },
+});
+```
+
+## Contract typing & version-skew safety
+
+Module Federation 2.0 can download a remote's **TypeScript types at build time** (`dts`). Treat exposed modules as **public APIs**: add optional props with defaults, never rename/remove props consumers rely on. If the host downloads remote types, a breaking contract change becomes a **build error** instead of a runtime crash.
+
+- **MUST** run contract tests in CI between shell and remotes.
+- **SHOULD** deprecate props with a window before removal; bump `@org/contracts` major on breaking change.
+
+## Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Version skew between shell and a remote | Semver `@org/contracts`; MF 2.0 `dts` build-time types; contract tests in CI |
+| Duplicate React/router instances | `singleton: true` + `requiredVersion` on both sides; symmetric `shared` |
+| CDN serving remotes goes down | Service Worker caching + offline fallback in `ErrorBoundary` |
+| CSS collisions between MFEs | CSS Modules / per-MFE prefix; shared design tokens via `@org/ui-kit` |
+| Uncontrolled `ui-kit` growth | Allow duplication first; promote to the kit only after a pattern is validated in 2+ MFEs |
+
+## The checkpoint that proves the design
+
+The critical moment is introducing the **second product**: if it requires modifying any capability MFE, the prop contract is wrong and must be fixed before continuing. A well-designed contract makes the 20th product as easy as the first.
+
+## Metrics of success
+
+- **Zero functional duplication** — a business rule changes in exactly one place.
+- **Bundle proportional to license** — a single-product tenant never downloads the full catalog.
+- **Independent deploy** — a capability fix reaches production without redeploying the others (< 15 min).
+- **License activation without redeploy** — a new module is live in the next session.
+- **INP < 100ms** on critical interactions; resilient during CDN/connectivity loss.
+
+## References
+
+- Module Federation 2.0 — https://module-federation.io/blog/announcement.html
+- Runtime API (`init`, `registerRemotes`, `loadRemote`) — https://module-federation.io/guide/runtime/runtime-api
+- `@module-federation/vite` — https://module-federation.io/
+- TanStack Router — https://tanstack.com/router

package/standards/web/single-spa/single-spa-standard.md

@@ -0,0 +1,196 @@
+---
+title: Single-SPA Microfrontends Standard
+platform: web
+track: single-spa
+load_when: "Building a web app composed of independently-deployed microfrontends that may use DIFFERENT frameworks, or that require hard runtime isolation (CSS/JS/lifecycle) per module."
+updated: 2026-06
+---
+
+# Single-SPA Microfrontends Standard
+
+> **Choose this track when** you need to compose microfrontends that are **independently deployed** and possibly built with **different frameworks/versions** (React + Angular + legacy), or when each module must have a **fully isolated lifecycle** (its own bootstrap/mount/unmount, CSS injected and removed on navigation). If your whole frontend is a single homogeneous React stack, prefer the [Module Federation track](../microfrontends/module-federation-standard.md) instead — it shares dependencies more efficiently and gives end-to-end typing.
+
+Single-SPA is a **top-level router/orchestrator**: a thin shell registers applications and decides which one is active for a given route. Each microfrontend exposes `bootstrap`/`mount`/`unmount` lifecycles.
+
+## Core rules
+
+- **MUST** keep the shell free of business logic. The shell only registers apps, owns global providers (auth, i18n, event bus) and passes them as `customProps`.
+- **MUST** expose `bootstrap`, `mount`, `unmount` lifecycles from each MFE entry (`src/spa.tsx`).
+- **MUST** set `domElementGetter` so the MFE mounts inside the shell container, not at the end of `<body>`.
+- **MUST** isolate CSS per MFE via `cssLifecycleFactory` (injected on mount, removed on unmount).
+- **MUST** wrap each MFE in an error boundary so one module failing never takes down the shell.
+- **MUST** give every MFE a unique route prefix matching its `base` (e.g. `/finance/*`).
+- **SHOULD** ship a standalone entry (`src/main.tsx`) so each MFE runs in isolation during development.
+- **SHOULD** share singletons (`react`, `react-dom`, router, query client) via an SystemJS import map to avoid duplicate instances.
+
+## Stack (2026)
+
+| Concern | Choice |
+|---|---|
+| Orchestrator | `single-spa` 6+ |
+| React adapter | `single-spa-react` |
+| Bundler plugin | `vite-plugin-single-spa` |
+| Framework | React 19 (18 still supported) + TypeScript strict |
+| Router (per MFE) | TanStack Router 1+ |
+| Module loader | SystemJS 6 + import maps |
+
+## MFE entry (`src/spa.tsx`)
+
+```tsx
+import React from 'react';
+import ReactDOMClient from 'react-dom/client';
+import singleSpaReact from 'single-spa-react';
+import { cssLifecycleFactory } from 'vite-plugin-single-spa/ex';
+import App from './App';
+
+// Context the shell injects into every MFE.
+export interface ShellProps {
+  i18n?: unknown;
+  eventBus?: unknown;
+  authContext?: unknown;
+}
+
+function ErrorFallback({ error }: { error: Error }) {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-red-50">
+      <div className="max-w-md rounded-lg bg-white p-6 shadow-lg">
+        <h2 className="mb-2 text-xl font-semibold text-red-600">Error en el módulo</h2>
+        <p className="mb-4 text-slate-600">{error.message}</p>
+        <button
+          onClick={() => window.location.reload()}
+          className="rounded bg-red-600 px-4 py-2 text-white hover:bg-red-700"
+        >
+          Recargar
+        </button>
+      </div>
+    </div>
+  );
+}
+
+const lifecycles = singleSpaReact({
+  React,
+  ReactDOMClient,
+  rootComponent: App,
+  errorBoundary: (err: Error) => <ErrorFallback error={err} />,
+  // CRITICAL: mount inside the shell container, not at the end of <body>.
+  domElementGetter: () => document.getElementById('single-spa-application')!,
+});
+
+const cssLc = cssLifecycleFactory('spa');
+
+export const bootstrap = [cssLc.bootstrap, lifecycles.bootstrap];
+export const mount = [cssLc.mount, lifecycles.mount];
+export const unmount = [cssLc.unmount, lifecycles.unmount];
+```
+
+> **Why `domElementGetter` is mandatory:** without it, `single-spa-react` creates a fresh `<div>` at the end of `<body>` and the MFE renders *outside* the shell layout — mounted correctly but invisible to the user. The shell must expose `<div id="single-spa-application">` in its layout.
+
+## MFE Vite config (`vite.config.ts`)
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import vitePluginSingleSpa from 'vite-plugin-single-spa';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    vitePluginSingleSpa({
+      serverPort: 3001,                  // unique per module
+      spaEntryPoints: 'src/spa.tsx',
+      cssStrategy: 'singleMife',         // CSS injected/removed on mount/unmount
+      projectId: 'finance-module',
+    }),
+  ],
+  server: { port: 3001, cors: true },
+  base: '/finance/',                     // route prefix
+});
+```
+
+## Shell registration (`app-shell/src/microfrontends/register.ts`)
+
+```ts
+import { registerApplication, start } from 'single-spa';
+
+const shared = {
+  i18n: i18nInstance,
+  eventBus,
+  authContext: authStore.getState(),
+};
+
+registerApplication({
+  name: 'finance',
+  app: () => System.import('http://localhost:3001/finance/spa.js'),
+  activeWhen: ['/finance'],
+  customProps: shared,
+});
+
+registerApplication({
+  name: 'inventory',
+  app: () => System.import('http://localhost:3002/inventory/spa.js'),
+  activeWhen: ['/inventory'],
+  customProps: shared,
+});
+
+start();
+```
+
+Shell import map (`app-shell/index.html`) — pins shared singletons:
+
+```html
+<script type="systemjs-importmap">
+{
+  "imports": {
+    "react": "https://cdn.jsdelivr.net/npm/react@19/umd/react.production.min.js",
+    "react-dom": "https://cdn.jsdelivr.net/npm/react-dom@19/umd/react-dom.production.min.js",
+    "single-spa": "https://cdn.jsdelivr.net/npm/single-spa@6/lib/system/single-spa.min.js"
+  }
+}
+</script>
+<script src="https://cdn.jsdelivr.net/npm/systemjs@6/dist/system.min.js"></script>
+```
+
+## Port convention
+
+| Module | Port | Role |
+|---|---|---|
+| app-shell | 3000 | Orchestrator |
+| finance | 3001 | MFE |
+| inventory | 3002 | MFE |
+| hr | 3003 | MFE |
+| crm | 3004 | MFE |
+
+## Per-MFE routing (TanStack Router)
+
+Every route MUST carry the module prefix that matches `base`:
+
+```tsx
+const dashboardRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/finance/dashboard',
+  component: Dashboard,
+});
+```
+
+## Checklist
+
+**MFE**
+- [ ] `vite-plugin-single-spa` + `single-spa-react` installed
+- [ ] `src/spa.tsx` exports `bootstrap`/`mount`/`unmount`
+- [ ] `cssLifecycleFactory` wired for CSS isolation
+- [ ] `errorBoundary` implemented
+- [ ] **`domElementGetter` → `#single-spa-application`** ⚠️
+- [ ] Unique port + `base` prefix; all routes use the prefix
+- [ ] `cors: true`; standalone `src/main.tsx` for dev
+
+**Shell**
+- [ ] `single-spa` installed; import map with shared singletons
+- [ ] `registerApplication` per MFE + `start()`
+- [ ] `customProps` with i18n/auth/eventBus
+- [ ] `<div id="single-spa-application">` present in layout ⚠️
+
+## References
+
+- Single-SPA — https://single-spa.js.org/
+- single-spa-react — https://single-spa.js.org/docs/ecosystem-react/
+- vite-plugin-single-spa — https://github.com/single-spa/vite-plugin-single-spa

package/standards/web/spa/spa-standard.md

@@ -0,0 +1,53 @@
+---
+title: Single-Page Application (SPA) Standard
+platform: web
+track: spa
+load_when: "Building one cohesive web application that ships as a single deployable — no microfrontends, no runtime composition."
+updated: 2026-06
+---
+
+# Single-Page Application (SPA) Standard
+
+> **Choose this track** for a single, cohesive app deployed as one unit. It's the default for most products. Only move to [Single-SPA](../single-spa/single-spa-standard.md) or [Module Federation](../microfrontends/module-federation-standard.md) when you have a real need for independently-deployed modules — don't adopt microfrontend complexity speculatively.
+
+A monolithic SPA still follows the same Clean Architecture + DDD folder structure and conventions as every web track. See [`frontend-architecture.md`](../_base/frontend-architecture.md) and [`frontend-standards.md`](../_base/frontend-standards.md) for the shared rules; this document only states what is specific to the single-deployable case.
+
+## Core rules
+
+- **MUST** ship as a single Vite build; no `remoteEntry`/federation, no SystemJS import maps.
+- **MUST** use TanStack Router file-based routing with pathless layouts for auth/app boundaries.
+- **MUST** code-split per route (automatic with TanStack Router) to keep the initial bundle < 500KB gzipped.
+- **SHOULD** organize by business module/domain/feature, not by technical layer.
+- **SHOULD** lazy-load heavy, rarely-used routes and features.
+
+## Vite config (`vite.config.ts`)
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { tanstackRouter } from '@tanstack/router-plugin/vite';
+
+export default defineConfig({
+  plugins: [
+    tanstackRouter({ target: 'react', autoCodeSplitting: true }),
+    react(),
+  ],
+  build: { target: 'esnext' },
+});
+```
+
+## When to graduate to microfrontends
+
+Adopt a microfrontend track only when **at least one** is true:
+
+- Independent teams need to deploy modules on **separate release cadences**.
+- A capability is **reused across multiple products** with different layouts.
+- You need to **enable/disable modules per tenant/license at runtime** (→ Module Federation).
+- You must integrate modules built with **different frameworks** (→ Single-SPA).
+
+Until then, a well-structured SPA is faster to build, debug and deploy.
+
+## References
+
+- TanStack Router — https://tanstack.com/router
+- Vite — https://vite.dev/