Saltar al contenido principal

​
Principios Básicos

Este monorepo sigue una arquitectura limpia y escalable diseñada para el desarrollo server-first utilizando Next.js App Router, TypeScript, XState y Yup. Establece estándares para:
  • Separación de Responsabilidades: Delimitando claramente las responsabilidades entre capas (UI, Actions, Machines, Services) siguiendo los principios de la Arquitectura en Capas.
  • Soporte para Microfrontends: Permitiendo el desarrollo y despliegue independiente de aplicaciones de dominio de negocio distintas utilizando un enfoque de Arquitectura de Microfrontends.
  • Reutilización de código: Maximizando el intercambio de código entre aplicaciones mediante paquetes centralizados.
  • Orquestación del estado del servidor: Utilizando máquinas de estado XState tipadas (Patrón State) para gestionar procesos de negocio complejos del lado del servidor, orquestando llamadas a la Capa de Servicios.
  • Capa de Servicios Estructurada: Empleando una estructura orientada al dominio (Patrón Strategy, Factory Method/Service Locator) para definir abstracciones de servicio (interfaces, DTOs de métodos) separadamente de las implementaciones concretas, invocadas por las máquinas de estado.
Para una visión detallada del flujo de trabajo principal, consulta la Guía del Flujo de Trabajo Principal. Para detalles específicos sobre la implementación del backend, consulta la Guía de Backend y Lógica Central. Para detalles del frontend, consulta la Guía de Desarrollo Frontend. Para los estándares de Git, consulta la Guía de Convenciones de Git.

​
Estructura del Monorepo

El proyecto está organizado en apps (unidades desplegables/microfrontends) y packages (código compartido).
Estructura Raíz del Proyecto
.
├── apps/
│   ├── web/                 # Aplicación UI principal o Shell (opcional)
│   ├── radicacion/          # Aplicación de dominio de negocio (ej. Radicación de Documentos)
│   ├── asignacion/          # Otro microfrontend (ej. Asignación de Casos)
│   └── …                    # Otras aplicaciones específicas del dominio
├── packages/
│   ├── core/                # Lógica de negocio central compartida y tipos fundamentales
│   │   ├── actions/         # Server Actions (`'use server'`) - Validar entrada, iniciar Máquinas
│   │   ├── machines/        # Máquinas de estado XState - Orquestar lógica de negocio, llamar Servicios
│   │   ├── services/        # Capa de Servicios de lógica de negocio/dominio - Implementar operaciones específicas
│   │   │   └── [domain]/    # ej. 'user', 'radicacion'
│   │   │       ├── domain/  # Abstracción de Servicio y Tipos de Dominio (Interfaz + DTOs)
│   │   │       │   ├── [Domain]Service.ts  # ej. UserService.ts (SOLO Interfaz/Contrato)
│   │   │       │   └── [Domain]Types.ts    # ej. UserTypes.ts (SOLO DTOs de Entrada/Salida de métodos)
│   │   │       ├── implementations/        # Implementaciones Concretas de Servicio (Patrón Strategy)
│   │   │       │   └── *.ts # ej. DefaultUserService.ts, AdminUserService.ts
│   │   │       ├── serviceMap.ts # Resuelve la implementación (Factory Method/Service Locator)
│   │   │       └── index.ts      # Exporta la función factory/localizadora del servicio
│   │   ├── types/           # Tipos/interfaces TypeScript BASE compartidos (no específicos del servicio)
│   │   │   ├── common/      # Tipos verdaderamente genéricos (ej. PaginationResult)
│   │   │   ├── entities/    # Modelos de datos/entidades centrales (ej. User, Document)
│   │   │   │   ├── User.ts
│   │   │   │   └── Document.ts
│   │   │   │   └── ...
│   │   │   ├── machines/    # Tipos de máquinas XState (Context, Events), organizados por máquina/dominio
│   │   │   │   ├── user/    # ej. tipos para máquinas de usuario
│   │   │   │   │   └── UserCreationMachineTypes.ts
│   │   │   │   ├── radicacion/ # ej. tipos para máquinas de radicación
│   │   │   │   │   └── DocumentIntakeMachineTypes.ts
│   │   │   │   └── ...
│   │   │   └── index.ts     # Opcional: Re-exportar tipos clave para importaciones de nivel superior más fáciles
│   │   └── validation/      # Esquemas de validación Yup - Usados por Actions
│   ├── hooks/               # Hooks de React compartidos (Intereses transversales)
│   └── config/              # Configuración compartida, variables de entorno, feature flags
├── tsconfig.json            # Configuración base de TypeScript (paths configurados aquí)
├── turbo.json               # Configuración de Turborepo
└── package.json             # Archivo raíz del gestor de paquetes (pnpm workspace)
Nota: Los componentes UI son proporcionados por la librería externa mappnext/ds-tw, instalada como una dependencia.

​
Comandos y Configuración

Comandos estándar ejecutados desde la raíz del monorepo:
Comandos Comunes de Desarrollo
# Instalar todas las dependencias para todas las apps y paquetes usando pnpm workspaces
pnpm install

# Ejecutar servidor de desarrollo para TODAS las apps concurrentemente usando Turborepo
pnpm dev

# Construir todas las apps y paquetes para producción usando Turborepo
pnpm build

# Ejecutar servidor de desarrollo para una app ESPECÍFICA (ej. radicacion)
# Reemplaza 'radicacion' con el nombre de la app/paquete deseado
pnpm --filter radicacion dev

# Construir solo una app/paquete ESPECÍFICO y sus dependencias
pnpm turbo build --filter=radicacion...

# Ejecutar tests en todo el monorepo (requiere script 'test' en package.json)
pnpm test

# Linting de todo el código base (requiere script 'lint' en package.json)
pnpm lint

​
Roles de los Paquetes Compartidos (packages/)

La funcionalidad compartida se organiza en paquetes dedicados. Los componentes UI provienen de una librería externa.
PaqueteDescripciónEjemplo de Uso Estándar
@coreCentro neurálgico para la lógica de dominio: actions, machines (Patrón State), services (siguiendo patrones Strategy/Factory con separación dominio/impl), tipos core (entidades, comunes, machine), esquemas de validación.import { createUserAction } from '@core/actions';
@hooksHooks de React reutilizables para intereses transversales o lógica UI compleja.import { useFormValidation } from '@hooks/forms';
@configAcceso a variables de entorno, configuración en tiempo de ejecución, feature flags.import { isBetaFeatureEnabled } from '@config';
mappnext/ds-tw/*Librería UI Obligatoria (Externa). Proporciona todos los componentes UI estándar.import { Button } from 'mappnext/ds-tw/atoms/Button';

​
Stack Tecnológico

Las tecnologías centrales exigidas por esta arquitectura:
HerramientaPropósitoUbicación Clave / Área de Uso
Next.jsFramework React full-stackapps/* (App Router, Server Components, Server Actions)
TypeScriptTipado estáticoTodo el código base (.ts, .tsx)
XStateMáquinas de estado y flujos de trabajopackages/core/machines/ (invocado por Actions, llama a Services)
YupDefinición y validación de esquemaspackages/core/validation/ (usado por actions)
TurborepoSistema de build/orquestador para monoreposturbo.json, Comandos raíz
pnpmGestor de paquetes eficientepackage.json raíz, workspaces
ReactLibrería UI Frontendapps/*, packages/hooks
mappnext/ds-twLibrería de Componentes UI EstándarDependencia Externa, Importada en apps/*
TailwindCSSFramework CSS Utility-firstUsado por mappnext/ds-tw y potencialmente en apps/*