Visión General y Configuración

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.

Paquete	Descripción	Ejemplo de Uso Estándar
`@core`	Centro 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';`
`@hooks`	Hooks de React reutilizables para intereses transversales o lógica UI compleja.	`import { useFormValidation } from '@hooks/forms';`
`@config`	Acceso 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:

Herramienta	Propósito	Ubicación Clave / Área de Uso
Next.js	Framework React full-stack	`apps/*` (App Router, Server Components, Server Actions)
TypeScript	Tipado estático	Todo el código base (`.ts`, `.tsx`)
XState	Máquinas de estado y flujos de trabajo	`packages/core/machines/` (invocado por Actions, llama a Services)
Yup	Definición y validación de esquemas	`packages/core/validation/` (usado por actions)
Turborepo	Sistema de build/orquestador para monorepos	`turbo.json`, Comandos raíz
pnpm	Gestor de paquetes eficiente	`package.json` raíz, workspaces
React	Librería UI Frontend	`apps/*`, `packages/hooks`
`mappnext/ds-tw`	Librería de Componentes UI Estándar	Dependencia Externa, Importada en `apps/*`
TailwindCSS	Framework CSS Utility-first	Usado por `mappnext/ds-tw` y potencialmente en `apps/*`

Guías y Buenas Prácticas

Estándares MappTech

Artículos y Charlas

Tutoriales y Guías

Visión General y Configuración

Principios Básicos

Estructura del Monorepo

Comandos y Configuración

Roles de los Paquetes Compartidos (`packages/`)

Stack Tecnológico

​Principios Básicos

​Estructura del Monorepo

​Comandos y Configuración

​Roles de los Paquetes Compartidos (packages/)

​Stack Tecnológico

Principios Básicos

Estructura del Monorepo

Comandos y Configuración

Roles de los Paquetes Compartidos (`packages/`)

Stack Tecnológico