From 0cfd05a9bcd00bba3f8a15183b37a90d98df4f54 Mon Sep 17 00:00:00 2001 From: Alberto Arroyo Raygada Date: Thu, 28 May 2026 11:51:51 -0500 Subject: [PATCH 1/6] docs: add UMS React web frontend reference portal --- docs/architecture/web-frontend/README.md | 35 ++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/architecture/web-frontend/README.md diff --git a/docs/architecture/web-frontend/README.md b/docs/architecture/web-frontend/README.md new file mode 100644 index 00000000..063d4f2f --- /dev/null +++ b/docs/architecture/web-frontend/README.md @@ -0,0 +1,35 @@ +# UMS React Web Frontend Applied Reference + +> Language: [English](./README.md) | [Espanol](./README.es.md) + +This section documents how the UMS React Web implementation applies the Evolith Web Frontend Standard - React. + +UMS is an applied reference, not the source of universal frontend standards. Reusable rules belong in Evolith. UMS keeps concrete product routes, local API headers, product modules, source evidence, and implementation-specific adaptations. + +## Documents + +| Document | Purpose | +|---|---| +| [UMS React Applied Reference](./ums-react-applied-reference.md) | Evidence-based mapping between Evolith React topics and UMS source files. | + +## Authority boundary + +| Concern | Evolith | UMS | +|---|---|---| +| Reusable standards | Owns principles, boilerplate rules, quality gates, and promotion criteria | Consumes standards | +| Product implementation | References examples only | Owns concrete source code and local decisions | +| UI design system | Owns token governance and accessibility rules | Owns actual UMS token values and components | +| Data access | Owns reusable boundary requirements | Owns UMS API URLs, headers, CSRF behavior, and tenant strategy | + +## Current evidence scope + +This reference is based on the current React app under: + +```text +src/apps/ums.web-app +``` + +Key observed sources include app bootstrap, routing, layout shell, HTTP context/client, Tailwind configuration, and Material Design 3 token definitions. + +--- +[Back to Architecture Portal](../index.md) From 6a39821e0769a5fe271090c9634fa5354fbf6558 Mon Sep 17 00:00:00 2001 From: Alberto Arroyo Raygada Date: Thu, 28 May 2026 11:52:28 -0500 Subject: [PATCH 2/6] docs: add Spanish UMS React web frontend reference portal --- docs/architecture/web-frontend/README.es.md | 35 +++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/architecture/web-frontend/README.es.md diff --git a/docs/architecture/web-frontend/README.es.md b/docs/architecture/web-frontend/README.es.md new file mode 100644 index 00000000..086dc4db --- /dev/null +++ b/docs/architecture/web-frontend/README.es.md @@ -0,0 +1,35 @@ +# Referencia Aplicada Web Frontend React de UMS + +> Idioma: [English](./README.md) | [Espanol](./README.es.md) + +Esta seccion documenta como la implementacion React Web de UMS aplica el Estandar Web Frontend React de Evolith. + +UMS es una referencia aplicada, no la fuente de estandares frontend universales. Las reglas reutilizables pertenecen a Evolith. UMS conserva rutas concretas de producto, headers locales de API, modulos de producto, evidencia de codigo fuente y adaptaciones especificas de implementacion. + +## Documentos + +| Documento | Proposito | +|---|---| +| [Referencia Aplicada React UMS](./ums-react-applied-reference.es.md) | Mapeo basado en evidencia entre topicos React de Evolith y archivos fuente de UMS. | + +## Limite de autoridad + +| Aspecto | Evolith | UMS | +|---|---|---| +| Estandares reutilizables | Posee principios, reglas boilerplate, quality gates y criterios de promocion | Consume estandares | +| Implementacion de producto | Referencia ejemplos solamente | Posee codigo fuente concreto y decisiones locales | +| Sistema de diseno UI | Posee gobierno de tokens y reglas de accesibilidad | Posee valores de tokens y componentes UMS concretos | +| Acceso a datos | Posee requerimientos reutilizables de frontera | Posee URLs, headers, comportamiento CSRF y estrategia de tenant de UMS | + +## Alcance de evidencia actual + +Esta referencia se basa en la app React actual ubicada en: + +```text +src/apps/ums.web-app +``` + +Las fuentes observadas incluyen bootstrap de aplicacion, routing, layout shell, contexto/cliente HTTP, configuracion Tailwind y definiciones de tokens Material Design 3. + +--- +[Volver al Portal de Arquitectura](../index.es.md) From 8d489f86794367cf1c440aa26d081743ee60de4b Mon Sep 17 00:00:00 2001 From: Alberto Arroyo Raygada Date: Thu, 28 May 2026 11:53:10 -0500 Subject: [PATCH 3/6] docs: add UMS React applied reference mapping --- .../ums-react-applied-reference.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/architecture/web-frontend/ums-react-applied-reference.md diff --git a/docs/architecture/web-frontend/ums-react-applied-reference.md b/docs/architecture/web-frontend/ums-react-applied-reference.md new file mode 100644 index 00000000..27bbdf8f --- /dev/null +++ b/docs/architecture/web-frontend/ums-react-applied-reference.md @@ -0,0 +1,107 @@ +# UMS React Applied Reference + +> Language: [English](./ums-react-applied-reference.md) | [Espanol](./ums-react-applied-reference.es.md) + +## 1. Purpose + +This document maps the UMS React Web implementation to the Evolith Web Frontend Standard - React. It is evidence for the current product implementation, not a universal standard. + +Reusable rules belong in Evolith. UMS-specific details remain here unless promoted through an Evolith ADR, governance standard, or canonical pattern. + +## 2. Source scope + +The applied reference covers: + +```text +src/apps/ums.web-app +``` + +Observed implementation profile: + +| Concern | UMS implementation | +|---|---| +| Runtime | React 18.3.1 | +| Build | Vite 5.4.10 | +| Language | TypeScript | +| Routing | React Router DOM 6.30.3 | +| Server state | TanStack React Query 5.100.9 | +| Client state | Zustand 5.0.13 | +| Runtime validation | Zod 4.4.3 | +| HTTP | Axios 1.16.0 | +| Styling | TailwindCSS 3.4.19 plus CSS variables | +| Mocking | MSW 2.14.6 | +| Unit/component tests | Vitest and Testing Library | +| E2E | Playwright | + +## 3. Evolith to UMS mapping + +| Evolith topic | UMS source evidence | Classification | +|---|---|---| +| App bootstrap | `src/apps/ums.web-app/src/main.tsx` centralizes React StrictMode, React Query provider, locale synchronization, request context configuration, and optional MSW startup. | Applied evidence | +| Server-state provider | `main.tsx` creates one `QueryClient` with shared default query options. | Candidate Evolith profile; exact defaults remain local | +| Routing | `src/apps/ums.web-app/src/App.tsx` uses `BrowserRouter`, route-level lazy imports, `Suspense`, `RouteLoader`, and fallback redirects. | Applied evidence | +| Error boundary | `App.tsx` wraps the routed application with `AppErrorBoundary`. | Reusable pattern | +| Layout shell | `src/apps/ums.web-app/src/presentation/shared/layouts/MainLayout.tsx` composes top app bar, nav rail, content region, notification behavior, and idle timeout integration. | Pattern reusable; concrete components and timeout are local | +| Material Design 3 tokens | `src/apps/ums.web-app/src/index.css` defines light/dark Material Design 3 role tokens as CSS variables. | Token governance candidate; concrete values are local | +| Tailwind token bridge | `src/apps/ums.web-app/tailwind.config.js` exposes `m3.*` semantic colors through `hsl(var(--token))`. | Boilerplate candidate | +| HTTP boundary | `src/apps/ums.web-app/src/infrastructure/http/httpClient.ts` centralizes Axios setup, request headers, CSRF, and normalized errors. | Reusable boundary pattern; headers are local | +| Request context | `src/apps/ums.web-app/src/infrastructure/http/request-context.ts` centralizes user and language request context and environment-based API base URL. | Reusable pattern; tenant placeholder is local technical debt | +| Testing profile | `src/apps/ums.web-app/package.json` declares Vitest, Testing Library, MSW, and Playwright. | Candidate quality gate profile | + +## 4. Items that should remain UMS-local + +| Item | Reason | +|---|---| +| Product routes such as `/tenants`, `/users`, `/delegations`, `/profiles`, and `/feature-flags` | UMS domain navigation, not reusable boilerplate. | +| Concrete dashboard screen names | UMS bounded-context implementation details. | +| `X-User-Id`, `X-Language`, and `X-Tenant-Id` header names | API-specific contract. Evolith should define the pattern, not the names. | +| `DEV_TENANT_ID` | Development placeholder and not suitable as an enterprise standard. | +| Indigo/Violet token values | Product branding choice. Evolith owns token roles, not these values. | +| Idle timeout value of 15 minutes | UMS security/session policy. Evolith can require configurability. | +| TopAppBar and NavRail component names | UMS component implementation. Evolith owns the application shell pattern. | + +## 5. Items to promote to Evolith + +| Candidate | Promotion target | +|---|---| +| React application folder structure with `domain`, `application`, `infrastructure`, and `presentation` | Evolith React boilerplate standard | +| Root provider composition pattern | Evolith React bootstrap guidance | +| Route-level lazy screen loading | Evolith React routing standard | +| Material Design 3 token roles via CSS variables | Evolith UI design-system standard | +| Tailwind semantic token mapping | Evolith React boilerplate standard | +| Centralized HTTP/request context boundary | Evolith data access standard | +| Testing stack profile with Vitest, Testing Library, MSW, and Playwright | Evolith frontend quality gates | + +## 6. Items requiring ADR or formal standard promotion + +| Item | Required action | +|---|---| +| React + Vite as default enterprise frontend baseline | Evolith ADR | +| TanStack React Query as server-state baseline | Evolith ADR or engineering standard | +| Zustand as lightweight client-state profile | Evolith ADR or optional profile | +| Material Design 3 token-based UI standard | Evolith UI/design-system standard and possible ADR | +| Zod as runtime validation profile | Evolith ADR or data-contract standard | +| MSW plus Playwright as standard testing profile | Evolith testing standard or ADR | + +## 7. Current gaps and follow-up actions + +| Gap | Recommendation | +|---|---| +| Development tenant identifier is hardcoded in request context | Replace with authenticated tenant resolution or environment-safe development adapter. | +| UMS applied reference depends on source conventions not yet fully enforced by automation | Extend documentation audit with frontend structure checks if required. | +| MD3 token values are product-local but not yet linked to an Evolith design-system ADR | Promote token governance to Evolith before making it mandatory. | +| Protected route pattern is not documented in this applied reference | Add when authorization guards are formalized in source. | + +## 8. Validation checklist + +Before changing UMS React Web architecture, validate: + +- The change is classified as Evolith standard, UMS local decision, or promotion candidate. +- Shared patterns remain independent from UMS product language. +- Product-specific route names, headers, tenant IDs, and branding stay in UMS. +- Any reusable rule is proposed in Evolith first. +- English and Spanish documentation are updated together. +- Markdown remains UTF-8 clean and free from decorative icons. + +--- +[Back to Web Frontend Portal](./README.md) From c74fe3ec0c640a10ff6e2465d731b56725e3c685 Mon Sep 17 00:00:00 2001 From: Alberto Arroyo Raygada Date: Thu, 28 May 2026 11:53:45 -0500 Subject: [PATCH 4/6] docs: add Spanish UMS React applied reference mapping --- .../ums-react-applied-reference.es.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/architecture/web-frontend/ums-react-applied-reference.es.md diff --git a/docs/architecture/web-frontend/ums-react-applied-reference.es.md b/docs/architecture/web-frontend/ums-react-applied-reference.es.md new file mode 100644 index 00000000..4badb3dd --- /dev/null +++ b/docs/architecture/web-frontend/ums-react-applied-reference.es.md @@ -0,0 +1,107 @@ +# Referencia Aplicada React UMS + +> Idioma: [English](./ums-react-applied-reference.md) | [Espanol](./ums-react-applied-reference.es.md) + +## 1. Proposito + +Este documento mapea la implementacion React Web de UMS contra el Estandar Web Frontend React de Evolith. Es evidencia de la implementacion actual del producto, no un estandar universal. + +Las reglas reutilizables pertenecen a Evolith. Los detalles especificos de UMS permanecen aqui salvo que se promuevan mediante un ADR de Evolith, estandar de gobierno o patron canonico. + +## 2. Alcance de fuente + +La referencia aplicada cubre: + +```text +src/apps/ums.web-app +``` + +Perfil de implementacion observado: + +| Aspecto | Implementacion UMS | +|---|---| +| Runtime | React 18.3.1 | +| Build | Vite 5.4.10 | +| Lenguaje | TypeScript | +| Routing | React Router DOM 6.30.3 | +| Estado servidor | TanStack React Query 5.100.9 | +| Estado cliente | Zustand 5.0.13 | +| Validacion runtime | Zod 4.4.3 | +| HTTP | Axios 1.16.0 | +| Estilos | TailwindCSS 3.4.19 mas variables CSS | +| Mocking | MSW 2.14.6 | +| Tests unitarios/componentes | Vitest y Testing Library | +| E2E | Playwright | + +## 3. Mapeo Evolith hacia UMS + +| Topico Evolith | Evidencia fuente UMS | Clasificacion | +|---|---|---| +| Bootstrap de aplicacion | `src/apps/ums.web-app/src/main.tsx` centraliza React StrictMode, provider React Query, sincronizacion de locale, configuracion de request context y arranque opcional de MSW. | Evidencia aplicada | +| Provider de server-state | `main.tsx` crea un `QueryClient` con opciones compartidas de query. | Perfil candidato Evolith; defaults exactos permanecen locales | +| Routing | `src/apps/ums.web-app/src/App.tsx` usa `BrowserRouter`, imports lazy por ruta, `Suspense`, `RouteLoader` y redirecciones fallback. | Evidencia aplicada | +| Error boundary | `App.tsx` envuelve la aplicacion ruteada con `AppErrorBoundary`. | Patron reutilizable | +| Layout shell | `src/apps/ums.web-app/src/presentation/shared/layouts/MainLayout.tsx` compone top app bar, nav rail, region de contenido, comportamiento de notificaciones e integracion idle timeout. | Patron reutilizable; componentes concretos y timeout son locales | +| Tokens Material Design 3 | `src/apps/ums.web-app/src/index.css` define tokens de roles Material Design 3 light/dark como variables CSS. | Candidato de gobierno de tokens; valores concretos son locales | +| Puente Tailwind de tokens | `src/apps/ums.web-app/tailwind.config.js` expone colores semanticos `m3.*` mediante `hsl(var(--token))`. | Candidato boilerplate | +| Frontera HTTP | `src/apps/ums.web-app/src/infrastructure/http/httpClient.ts` centraliza configuracion Axios, headers, CSRF y errores normalizados. | Patron de frontera reutilizable; headers son locales | +| Request context | `src/apps/ums.web-app/src/infrastructure/http/request-context.ts` centraliza contexto de usuario e idioma y base URL por entorno. | Patron reutilizable; placeholder de tenant es deuda tecnica local | +| Perfil de pruebas | `src/apps/ums.web-app/package.json` declara Vitest, Testing Library, MSW y Playwright. | Perfil candidato de quality gates | + +## 4. Items que deben permanecer locales en UMS + +| Item | Razon | +|---|---| +| Rutas de producto como `/tenants`, `/users`, `/delegations`, `/profiles` y `/feature-flags` | Navegacion de dominio UMS, no boilerplate reutilizable. | +| Nombres concretos de pantallas dashboard | Detalles de implementacion de bounded contexts UMS. | +| Headers `X-User-Id`, `X-Language` y `X-Tenant-Id` | Contrato especifico de API. Evolith debe definir el patron, no los nombres. | +| `DEV_TENANT_ID` | Placeholder de desarrollo y no apto como estandar empresarial. | +| Valores Indigo/Violet de tokens | Decision de branding del producto. Evolith posee roles de token, no estos valores. | +| Timeout idle de 15 minutos | Politica de seguridad/sesion UMS. Evolith puede exigir configurabilidad. | +| Nombres de componentes TopAppBar y NavRail | Implementacion de componentes UMS. Evolith posee el patron application shell. | + +## 5. Items a promover a Evolith + +| Candidato | Destino de promocion | +|---|---| +| Estructura React con `domain`, `application`, `infrastructure` y `presentation` | Estandar boilerplate React Evolith | +| Patron de composicion de providers raiz | Guia de bootstrap React Evolith | +| Lazy loading de pantallas a nivel ruta | Estandar de routing React Evolith | +| Roles de tokens Material Design 3 via variables CSS | Estandar de sistema de diseno UI Evolith | +| Mapeo de tokens semanticos Tailwind | Estandar boilerplate React Evolith | +| Frontera centralizada HTTP/request context | Estandar de acceso a datos Evolith | +| Perfil de pruebas con Vitest, Testing Library, MSW y Playwright | Quality gates frontend Evolith | + +## 6. Items que requieren ADR o promocion formal + +| Item | Accion requerida | +|---|---| +| React + Vite como baseline frontend empresarial por defecto | ADR Evolith | +| TanStack React Query como baseline de server-state | ADR Evolith o estandar de ingenieria | +| Zustand como perfil liviano de client-state | ADR Evolith o perfil opcional | +| Material Design 3 basado en tokens como estandar UI | Estandar UI/design-system Evolith y posible ADR | +| Zod como perfil de validacion runtime | ADR Evolith o estandar de contratos de datos | +| MSW mas Playwright como perfil estandar de testing | Estandar de pruebas Evolith o ADR | + +## 7. Brechas actuales y acciones de seguimiento + +| Brecha | Recomendacion | +|---|---| +| Identificador de tenant de desarrollo hardcodeado en request context | Reemplazar por resolucion de tenant autenticada o adaptador de desarrollo seguro por entorno. | +| La referencia aplicada UMS depende de convenciones de fuente aun no totalmente automatizadas | Extender la auditoria documental con checks de estructura frontend si se requiere. | +| Los valores de tokens MD3 son locales pero aun no enlazan a un ADR de sistema de diseno Evolith | Promover gobierno de tokens a Evolith antes de hacerlo obligatorio. | +| Patron de rutas protegidas no documentado en esta referencia aplicada | Agregar cuando los authorization guards se formalicen en fuente. | + +## 8. Checklist de validacion + +Antes de cambiar la arquitectura React Web de UMS, validar: + +- El cambio se clasifica como estandar Evolith, decision local UMS o candidato de promocion. +- Los patrones compartidos permanecen independientes del lenguaje de producto UMS. +- Rutas, headers, tenant IDs y branding especificos del producto permanecen en UMS. +- Toda regla reutilizable se propone primero en Evolith. +- Documentacion en ingles y espanol se actualiza en conjunto. +- Markdown permanece UTF-8 limpio y sin iconos decorativos. + +--- +[Volver al Portal Web Frontend](./README.es.md) From 5d21a11edcc8ecfe0af12e029ca3094e344c7d04 Mon Sep 17 00:00:00 2001 From: Alberto Arroyo Raygada Date: Thu, 28 May 2026 11:54:42 -0500 Subject: [PATCH 5/6] docs: link UMS React web frontend reference from architecture portal --- docs/architecture/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/architecture/index.md b/docs/architecture/index.md index 144b4e4b..9f83ff9f 100644 --- a/docs/architecture/index.md +++ b/docs/architecture/index.md @@ -62,6 +62,9 @@ Detailed engineering blueprints focusing on: - **[Shell Library Developer Guides](./shell-libraries/README.md)**: Comprehensive developer guides for all four shell libraries with independent and combined usage examples. - [Ums.Shell.Ddd](./shell-libraries/ddd.md) · [Ums.Shell.Factory](./shell-libraries/factory.md) · [Ums.Shell.Aop](./shell-libraries/aop.md) · [Ums.Shell.Bootstrapper](./shell-libraries/bootstrapper.md) · [Combined Usage](./shell-libraries/combined-usage.md) +### [Web Frontend](./web-frontend/README.md) +Applied React Web reference for UMS. This section maps current source evidence to the Evolith Web Frontend Standard - React while keeping product-specific implementation details local to UMS. + ### [Traceability Matrix](./traceability-matrix.md) Cross-reference of all Functional Stories (FS-01..16) to ADRs and Technical Enablers. From 1bd1d90ca828498935a22ca4d90bd1c419308d98 Mon Sep 17 00:00:00 2001 From: Alberto Arroyo Raygada Date: Thu, 28 May 2026 11:55:05 -0500 Subject: [PATCH 6/6] docs: link Spanish UMS React web frontend reference from architecture portal --- docs/architecture/index.es.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/architecture/index.es.md b/docs/architecture/index.es.md index 4f5d061f..2e4bc654 100644 --- a/docs/architecture/index.es.md +++ b/docs/architecture/index.es.md @@ -52,6 +52,9 @@ Planos detallados de ingeniería centrados en: - **[Formatos de Exportación ER](./blueprints-es/er-export-formats.md)**: Exportaciones SQL, Mermaid e imágenes del esquema. - **[Arquitectura de Librerías Shell](./blueprints-es/shell-library-architecture.md)**: Capa shell propia de UMS para patrones DDD y Factory heredados. +### [Web Frontend](./web-frontend/README.es.md) +Referencia aplicada React Web para UMS. Esta seccion mapea evidencia actual de codigo fuente contra el Estandar Web Frontend React de Evolith manteniendo los detalles especificos de producto dentro de UMS. + ### Relacionado — Diseño de Capa de Dominio - **[Portal DDD](../governance/construction/ddd-design/index.md)**: Bounded contexts, agregados, value objects, comandos, eventos y maquinas de estado para el producto completo. - **[Primitivas DDD](../governance/construction/ddd-design/11-ddd-primitives.md)**: Primitivas de dominio implementadas mediante la capa de librerías shell de UMS.