> ## 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.

# Backend y Lógica Central

> Guía detallada de la arquitectura backend dentro de packages/core, cubriendo Actions, Machines, Services, Types y Validation.

El directorio `packages/core` alberga la lógica de negocio central, desacoplada de cualquier implementación de UI específica.

| Carpeta       | Responsabilidad                                                                                                                                                                                                                                                                | Tecnologías / Patrones Clave                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actions/`    | Funciones del lado del servidor invocables desde el cliente. **Valida la entrada**, instancia e **inicia la máquina XState apropiada**, espera su resultado final.                                                                                                             | Next.js Server Actions                                                                                                                                         |
| `machines/`   | Define y gestiona flujos de trabajo complejos con estado (**Patrón State**). **Orquesta el flujo de la lógica de negocio**, preparando DTOs, invocando métodos en **implementaciones de Servicio** resueltas y procesando DTOs de salida.                                      | XState                                                                                                                                                         |
| `services/`   | Encapsula operaciones de dominio discretas mediante una **Capa de Servicios** estructurada (**Patrón Strategy**). Implementa tareas específicas (interacción con BD, llamadas API) invocadas *por* las máquinas, usando el contrato definido por su interfaz y DTOs de método. | TypeScript Interfaces/Classes. *Interfaz y DTOs de Método definidos en `services/[domain]/domain/`. Implementaciones en `services/[domain]/implementations/`.* |
| `types/`      | Define **estructuras de datos base** compartidas (Entities), tipos de utilidad comunes y **tipos para máquinas XState**, organizados en subdirectorios (`common/`, `entities/`, `machines/`). Excluye DTOs de métodos de servicio.                                             | TypeScript                                                                                                                                                     |
| `validation/` | Define esquemas de validación de datos, usados principalmente por `actions/` antes de iniciar una máquina.                                                                                                                                                                     | Yup (`InferType`)                                                                                                                                              |

*Para el flujo estándar que conecta estas capas, consulta la [Guía del Flujo de Trabajo Principal](./standards-workflow).*

***

## Estructura de la Capa de Servicios (`packages/core/services/[domain]/`)

Los servicios proporcionan implementaciones concretas de operaciones de negocio específicas, invocadas por las máquinas de estado. La estructura dentro de cada directorio de dominio de servicio (ej., `packages/core/services/user/`) sigue un patrón claro que promueve la separación de la abstracción de la implementación:

1. **`domain/`**: Este directorio define la **Capa de Abstracción** para el servicio. Contiene **solamente**:
   * `[Domain]Service.ts`: La `interface` TypeScript que define el contrato del servicio (ej., `UserService`). Especifica *qué* operaciones proporciona el servicio.
   * `[Domain]Types.ts`: Define los **Data Transfer Objects (DTOs)** – los tipos/interfaces TypeScript específicos para los parámetros de entrada (`input`) y valores de retorno (`output`) de cada método declarado en la interfaz `[Domain]Service.ts` (ej., `CreateUserMethodInput`, `CreateUserMethodOutput`). Especifica la *forma de los datos* con los que trabaja el servicio en su límite.
   * *Fundamentalmente, esta carpeta **no** contiene ninguna lógica de implementación ni hace referencia directa a tipos de otras capas como `validation`.*

2. **`implementations/`**: Contiene las clases concretas **Strategy** que **implementan** la interfaz `[Domain]Service.ts`. Cada archivo típicamente representa una estrategia o versión diferente de la lógica del servicio (ej., `DefaultUserService.ts`, `AdminUserService.ts`). Esto es *cómo* se realizan las operaciones del servicio, mapeando potencialmente los DTOs de entrada a tipos internos si es necesario.

3. **`serviceMap.ts`**: Implementa un patrón **Factory Method** o **Service Locator**. Típicamente exporta una función (ej., `getUserService`) que toma criterios (como un ID de cliente, rol de usuario, feature flag) y devuelve la instancia de servicio concreta apropiada del directorio `implementations/`. Este mapa o su función getter debe ser accesible *para la máquina XState* (ej., pasado a través del `context` o importado directamente si es apropiado).

4. **`index.ts`**: Un simple archivo `barrel file` que exporta la API pública del módulo de servicio, principalmente la función `factory/locator` de `serviceMap.ts` (ej., `export { getUserService } from './serviceMap';`).

***

## Tipos Centrales (`packages/core/types/`)

El directorio `types/` es crucial para mantener la consistencia y habilitar el análisis estático en toda la lógica central.

```text Estructura de packages/core/types/ theme={null}
types/
├── 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
```

* **Entities:** Representan las estructuras de datos centrales de la aplicación (ej., un objeto `User` que coincide con el esquema de la base de datos).
* **Machine Types:** Definen la forma del `Context` y los posibles `Events` para cada máquina XState, asegurando la seguridad de tipos durante las transiciones de estado y la ejecución lógica. Se mantienen separados de los Service DTOs.
* **Common Types:** Tipos de utilidad usados en diferentes dominios (ej., envoltorios de respuesta API estandarizados, estructuras de paginación).

***

## Validación (`packages/core/validation/`)

Toda entrada proveniente del cliente hacia una Server Action **debe** ser validada antes de ser procesada.

* Usa **Yup** para la definición y validación de esquemas.
* Los esquemas se definen en `packages/core/validation/`, típicamente organizados por dominio (ej., `userSchema.ts`).
* Las Server Actions importan y usan estos esquemas para validar la entrada.
* Usa `yup.InferType<typeof yourSchema>` para derivar tipos TypeScript directamente de los esquemas para usar en Actions y potencialmente como el tipo de entrada inicial para Machines (`validatedInput`).
* Los errores de validación deben resultar en un retorno temprano desde la Action con una respuesta de error estructurada (ver `ActionResult` en la [Guía del Flujo de Trabajo Principal](./standards-workflow)).