Diagrama UML de Componentes — ExpressMX

Resumen

El presente documento formaliza la vista de componentes del sistema ExpressMX siguiendo la notacion UML 2.5, expresada con la sintaxis flowchart de Mermaid para garantizar la trazabilidad entre el modelo y la implementacion. La arquitectura corresponde a un monorepo pnpm con tres aplicaciones de despliegue independiente (apps/web, apps/mobile-client, apps/mobile-provider) que reutilizan cinco paquetes compartidos (@expressmx/database, @expressmx/validations, @expressmx/types, @expressmx/utils y @expressmx/config). Cada componente se modela con el estereotipo <<component>> y expone interfaces (puertos UML) tipadas por contrato: REST/JSON sobre HTTPS protegido por JWT Bearer para clientes moviles, Server Actions sobre cookies de sesion HttpOnly para el panel administrativo, SMTP sobre HTTPS para correo transaccional y el protocolo de cable de Postgres para la persistencia.

El objetivo de la vista es hacer explicita la cohesion vertical entre tiers (cliente, aplicacion, datos) y la cohesion horizontal entre paquetes compartidos, evidenciando que ningun cliente movil depende directamente del paquete @expressmx/database, lo que preserva el principio de zero-trust/Backend-for-Frontend exigido por el caso practico.

Diagrama (PlantUML)

Fuente: uml-component-diagram.puml

Renderizar con: plantuml -tpng uml-component-diagram.puml

Inventario de componentes

Componente	Tipo	Archivo / ubicacion fuente	Proposito
mobile-client	Aplicacion Expo	`apps/mobile-client/package.json`	Aplicacion para usuarios finales; consume API REST con JWT.
mobile-provider	Aplicacion Expo	`apps/mobile-provider/package.json`	Aplicacion para prestadores; consume API REST con JWT.
Browser	Cliente externo	n/a	Renderiza el panel `web-admin` mediante HTTPS.
web-admin	Aplicacion Next.js 16	`apps/web/package.json`	Panel de administracion, API y orquestacion de tareas.
Dashboard Pages	Subcomponente	`apps/web/src/app/**/page.tsx`	Vistas server-rendered del panel administrativo.
API REST	Subcomponente	`apps/web/src/app/api/`, `apps/web/src/app/api/v1/`	Endpoints HTTP versionados para clientes moviles y dashboard.
Server Actions	Subcomponente	`apps/web/src/lib/dashboard/actions/**`	Mutaciones tipadas invocadas desde la UI server-rendered.
Auth Subsystem	Subcomponente	`apps/web/src/lib/auth/{guards,session,mobile}.ts`	Emite y verifica JWT/cookies, hash bcrypt, OTP.
RBAC Engine	Subcomponente	`apps/web/src/lib/dashboard/{rbac,rbac-shared,auth-gate}.ts`	Construye el viewer y resuelve permisos por rol.
Audit Logger	Subcomponente	`apps/web/src/lib/dashboard/audit.ts`	Registra mutaciones (`logAccion`) en la tabla de auditoria.
@expressmx/database	Package	`packages/database/package.json`	Pool `pg`, helpers de transaccion y queries SQL.
@expressmx/validations	Package	`packages/validations/package.json`	Esquemas Zod compartidos cliente-servidor.
@expressmx/types	Package	`packages/types/package.json`	DTOs y contratos derivados de los esquemas Zod.
@expressmx/config	Package	`packages/config/{eslint,typescript}`	Configuracion compartida de lint y `tsconfig`.
@expressmx/utils	Package	`packages/utils/package.json`	Helpers puros (formato, fechas, mapeos).
Neon Postgres	Servicio externo	`DATABASE_URL` (env)	Postgres serverless que aloja el esquema productivo.
Resend	Servicio externo	`RESEND_API_KEY` (env)	Envio de correo transaccional via SMTP/HTTPS.
Expo EAS	Servicio externo	`apps/mobile-*/eas.json`	Build y distribucion OTA de las apps Expo.
Vercel Edge	Servicio externo	`apps/web` (hosting)	Hosting serverless del panel Next.js.

Interfaces (UML ports)

JWT Bearer (Authorization: Bearer ...): contrato emitido por Auth Subsystem y consumido por mobile-client y mobile-provider al llamar a /api/v1/**. Token firmado con jose/HS256 y validado por apps/web/src/lib/auth/guards.ts.
Session Cookie: cookie HttpOnly emitida tras login del panel; transporta el sub que auth-gate.ts resuelve a un Viewer antes de invocar Server Actions o renderizar paginas.
Postgres wire protocol: TLS hacia Neon iniciado por el pool pg dentro de @expressmx/database. Es el unico canal de persistencia y solo es accesible desde web-admin (los clientes moviles no abren conexiones SQL).
REST/JSON: contrato HTTP versionado expuesto por API REST, descrito en el OpenAPI generado por apps/web/scripts/generate-openapi.ts.
SMTP/HTTPS: el subsistema de Auth y las Server Actions invocan a Resend (apps/web/src/lib/email.ts) para correo transaccional (verificacion, notificaciones SLA, recuperacion).

Trazabilidad

pnpm-workspace.yaml:1-5 declara apps/*, packages/* y packages/config/*, dando lugar a los nueve paquetes representados.
apps/web/package.json:23-26 confirma las dependencias workspace (@expressmx/database, @expressmx/types, @expressmx/utils, @expressmx/validations).
apps/mobile-client/package.json:15-18 y apps/mobile-provider/package.json:16-18 muestran que ambas apps Expo solo importan validations, types y utils, nunca database.
apps/web/src/lib/auth/guards.ts y apps/web/src/lib/auth/session.ts implementan el subcomponente Auth Subsystem (verificacion JWT y cookie).
apps/web/src/lib/dashboard/auth-gate.ts:1-20 implementa el flujo getViewer/requireViewer/requirePermiso que conecta sesion y RBAC.
apps/web/src/lib/dashboard/rbac.ts y rbac-shared.ts implementan RBAC Engine (matriz rol/permiso compartida cliente-servidor).
apps/web/src/lib/dashboard/audit.ts:1-15 implementa Audit Logger con logAccion y query/Tx de @expressmx/database.
apps/web/src/app/api/v1/** agrupa los endpoints publicados a clientes moviles, mientras que apps/web/src/app/api/{auth,clients,...} aloja los endpoints internos del dashboard.
apps/web/src/lib/email.ts encapsula la integracion con Resend.
packages/database/package.json:16-17 declara pg como unico driver, lo que fija el puerto Postgres del diagrama.
packages/validations/package.json:13 declara zod como dependencia raiz, habilitando los esquemas reutilizados en types.
packages/types/package.json:14-16 confirma que types reusa @expressmx/validations para derivar DTOs (linea punteada del diagrama).
packages/config/eslint/package.json y packages/config/typescript/*.json publican la configuracion compartida invocada por todos los paquetes.

Cubre Problema 2 (Arquitectura) del Caso Practico SOFTWARE 6.