Diagrama UML de Paquetes — Monorepo ExpressMX

Resumen

El proyecto ExpressMX se organiza como un monorepo gestionado con pnpm workspaces y orquestado con Turborepo. La estructura aplica el principio de modularidad: separa las aplicaciones consumidoras (apps/*) de las bibliotecas reutilizables (packages/*), aisla configuraciones compartidas (packages/config/*), mantiene la infraestructura declarativa fuera del grafo TypeScript (infra/*, migrations/*) y conserva la documentación viva en docs/*. Esta separación garantiza que las dependencias fluyan en una sola dirección — desde las apps hacia los paquetes, nunca al revés — eliminando ciclos y permitiendo construir, probar y desplegar cada superficie de forma independiente.

Este documento modela los paquetes como cajas estereotipadas UML (<<application>>, <<library>>, <<config>>, <<infrastructure>>, <<docs>>) y demuestra mediante un análisis de dependencias que el grafo es acíclico.

Diagrama (PlantUML)

Fuente: uml-package-diagram.puml

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

Las flechas continuas representan dependencias en tiempo de ejecución (campo dependencies del package.json). Las flechas punteadas con etiqueta devDep representan dependencias de desarrollo (campo devDependencies); estas no participan del bundle final pero sí del grafo de tipos. Las flechas punteadas con etiqueta consume y documenta indican relaciones lógicas (no expresadas en package.json).

Inventario de paquetes

Nombre	Ruta	Proposito	Exportaciones publicas	Dependencias internas
`@expressmx/web`	`apps/web`	Aplicacion Next.js 16 (App Router, RSC) que sirve la consola web administrativa, el portal de soporte y la API HTTP.	rutas `app/`, route handlers `/api/*`, scripts cron	`database`, `validations`, `types`, `utils`
`@expressmx/mobile-client`	`apps/mobile-client`	App movil para clientes finales (Expo + expo-router). Solicita servicios y consume la API de `apps/web`.	bundle Expo (`expo-router/entry`)	`types`, `validations`, `utils`
`@expressmx/mobile-provider`	`apps/mobile-provider`	App movil para prestadores (Expo). Recibe asignaciones, gestiona estado de orden y captura evidencia.	bundle Expo (`expo-router/entry`)	`types`, `validations`, `utils`
`@expressmx/database`	`packages/database`	Capa de acceso a datos: pool `pg`, queries SQL parametrizadas, ejecutor de migraciones, seeds.	`.` (pool y helpers), `./queries/`, `./migrations/`	(ninguna interna)
`@expressmx/validations`	`packages/validations`	Schemas Zod compartidos: validacion de inputs HTTP, formularios y payloads de cron.	`.` (todos los schemas)	(ninguna interna)
`@expressmx/types`	`packages/types`	Tipos TypeScript derivados de los schemas de Zod y modelos de dominio.	`.` (tipos)	`validations`
`@expressmx/utils`	`packages/utils`	Helpers puros sin efectos: format, parseo, fechas, conversiones.	`.` (helpers)	(ninguna interna)
`@expressmx/config-typescript`	`packages/config/typescript`	Configuraciones base de TypeScript reutilizables.	`./base`, `./nextjs`, `./expo`	(ninguna interna)
`@expressmx/config-eslint`	`packages/config/eslint`	Reglas ESLint compartidas para Next.js y Expo.	`./base`, `./nextjs`, `./expo`	(ninguna interna)
`infra/docker`	`infra/docker`	Reservado para `Dockerfile` y `docker-compose`.	no implementado (directorio vacio)	n/a
`infra/k8s`	`infra/k8s`	Reservado para manifiestos Kubernetes (`Deployment`, `Service`, `Ingress`).	no implementado (directorio vacio)	n/a
`migrations/`	`migrations/`	Migraciones SQL versionadas (`001`..`006`) ejecutadas por `@expressmx/database`.	scripts `.sql`	n/a (consumidos por `database`)
`docs/`	`docs/`	Documentacion viva: arquitectura, errores, mobile, sesiones, auth-recovery, design-source.	archivos Markdown y diagramas	n/a

Reglas de visibilidad

Paquetes publicos (consumidos por aplicaciones):

@expressmx/database — solo lo importa apps/web. Los clientes moviles nunca tocan la base de datos directamente: van por la API HTTP. Esto evita filtrar credenciales pg al bundle de Expo y aplica el principio de menor privilegio.
@expressmx/validations — lo importan web, mobile-client y mobile-provider. Single source of truth para validar inputs en cliente y servidor.
@expressmx/types — lo importan las tres apps. Garantiza coherencia en el contrato de datos entre web, mobile y API.
@expressmx/utils — lo importan las tres apps. Helpers puros sin lado-efecto, seguros para web y React Native.

Paquetes internos (utility de desarrollo, no se ven en el bundle de produccion):

@expressmx/config-typescript — solo aparece como devDependency. Sirve para extends en cada tsconfig.json.
@expressmx/config-eslint — solo aparece como devDependency de apps/web (las apps Expo usan expo lint con su propia config).

Ningun paquete depende de aplicaciones. Esta es la regla cardinal: el flujo es siempre apps/* -> packages/*, nunca al reves. Las apps son hojas en el grafo de modulos.

Analisis de ciclos

Recorrido manual del grafo (solo dependencies, sin devDependencies ya que estas no afectan el bundle de produccion y por construccion apuntan a config/* que es terminal):

apps/web -> @expressmx/database -> (terminal, no cycle)
apps/web -> @expressmx/validations -> (terminal, no cycle)
apps/web -> @expressmx/types -> @expressmx/validations -> (terminal, no cycle)
apps/web -> @expressmx/utils -> (terminal, no cycle)

apps/mobile-client -> @expressmx/types -> @expressmx/validations -> (terminal, no cycle)
apps/mobile-client -> @expressmx/validations -> (terminal, no cycle)
apps/mobile-client -> @expressmx/utils -> (terminal, no cycle)

apps/mobile-provider -> @expressmx/types -> @expressmx/validations -> (terminal, no cycle)
apps/mobile-provider -> @expressmx/validations -> (terminal, no cycle)
apps/mobile-provider -> @expressmx/utils -> (terminal, no cycle)

Resultado: 0 ciclos detectados.

Propiedades estructurales que garantizan el resultado:

Las tres aplicaciones son nodos hoja: nada las importa porque ningun package.json declara dependencia hacia @expressmx/web, @expressmx/mobile-client o @expressmx/mobile-provider.
@expressmx/database, @expressmx/validations y @expressmx/utils son nodos terminales: no declaran dependencias internas en dependencies.
La unica arista entre paquetes es types -> validations. Como validations es terminal, esa cadena cierra inmediatamente.
El grafo es un DAG con dos niveles: aplicaciones (raices) y paquetes (hojas), con un unico arco types -> validations dentro del nivel hoja.

Verificacion de cobertura

Cada referencia @expressmx/* en algun package.json debe tener su flecha en el diagrama. Conteo:

apps/web/package.json declara 4 dependencies workspace (database, types, utils, validations) y 2 devDependencies workspace (config-typescript, config-eslint). Total 6 aristas. Cubiertas.
apps/mobile-client/package.json declara 3 dependencies workspace (types, utils, validations) y 1 devDependency workspace (config-typescript). Total 4 aristas. Cubiertas.
apps/mobile-provider/package.json declara 3 dependencies workspace (types, utils, validations) y 1 devDependency workspace (config-typescript). Total 4 aristas. Cubiertas.
packages/database/package.json declara 1 devDependency workspace (config-typescript). Cubierta.
packages/validations/package.json declara 1 devDependency workspace (config-typescript). Cubierta.
packages/types/package.json declara 1 dependency workspace (validations) y 1 devDependency workspace (config-typescript). Ambas cubiertas.
packages/utils/package.json declara 1 devDependency workspace (config-typescript). Cubierta.

Total: 19 referencias workspace:* en los package.json del monorepo. Las 19 aparecen como flechas (continuas o punteadas) en el diagrama anterior.

Nodos terminales y mas dependidos

Nodos sin dependencias entrantes (raices del grafo): @expressmx/web, @expressmx/mobile-client, @expressmx/mobile-provider. Las aplicaciones son consumidoras puras.
Nodos sin dependencias salientes a otros workspace packages: @expressmx/database, @expressmx/validations, @expressmx/utils, @expressmx/config-typescript, @expressmx/config-eslint. Son hojas en el DAG.
Paquete con mas dependientes en dependencies (mas-depended-upon): @expressmx/validations con 4 dependientes (web, mobile-client, mobile-provider, types). Le sigue @expressmx/types con 3, @expressmx/utils con 3 y @expressmx/database con 1.
Paquete mas reutilizado contando devDependencies: @expressmx/config-typescript con 7 dependientes (las 3 apps mas los 4 paquetes de runtime). Es el contrato de configuracion mas estable del monorepo.

Cubre Problema 2 (Arquitectura — modularidad del monorepo).

↑ Volver arriba

Diagrama de paquetes