> ## Documentation Index
> Fetch the complete documentation index at: https://blog.mapptech.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Visión General y Configuración

> Introducción a la arquitectura monorepo server-first de MappTech, principios básicos, estructura, stack tecnológico y comandos de configuración esenciales.

## 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](./standards-workflow).*
*Para detalles específicos sobre la implementación del backend, consulta la [Guía de Backend y Lógica Central](./standards-backend).*
*Para detalles del frontend, consulta la [Guía de Desarrollo Frontend](./standards-frontend).*
*Para los estándares de Git, consulta la [Guía de Convenciones de Git](./standards-git).*

***

## Estructura del Monorepo

El proyecto está organizado en `apps` (unidades desplegables/microfrontends) y `packages` (código compartido).

```text Estructura Raíz del Proyecto theme={null}
.
├── 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:

```bash Comandos Comunes de Desarrollo theme={null}
# 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';` |

<Nota>
  Los alias de paquetes (`@core`, `@hooks`, `@config`) se configuran en el `tsconfig.json` raíz bajo `paths`. Estos alias **deben** usarse para importar código compartido desde `packages/`. Los componentes UI **deben** importarse directamente desde `mappnext/ds-tw/*`.
</Nota>

***

## 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/*`            |