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

# customer-core

> customer-core es la capa que sabe quién es un cliente. Resuelve identidades entre los sistemas que una empresa ya opera, guarda sus atributos y su consentimiento, registra lo que hace y calcula a qué segmentos pertenece.

> Traducción. Autoritativo: [`../../../modules/core/prd.md`](/modules/core/prd).

> customer-core es la capa que sabe quién es un cliente. Resuelve identidades entre los sistemas que
> una empresa ya opera, guarda sus atributos y su consentimiento, registra lo que hace y calcula a
> qué segmentos pertenece. Fidelización, mensajería y CRM son todos consumidores suyos. Nadie más en
> la suite es dueño de un contacto, y nada más tiene permitido serlo.

## Para quién es

Nadie compra `core`. No tiene sección propia en la consola ni línea en una factura, y ese es el
punto: es la infraestructura sobre la que se paran los otros tres módulos. Sus usuarios son
internos.

| Consumidor                  | Depende de core para                                                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **loyalty**                 | El contacto sobre el que trata un programa, los eventos que sus reglas evalúan, los segmentos que apuntan sus campañas |
| **messaging**               | A quién enviar, por qué canal, con qué consentimiento, y si está suprimido                                             |
| **crm**                     | El timeline 360, que es una mezcla de los eventos de core con los registros de los otros módulos                       |
| **Cualquier módulo futuro** | Lo mismo, sin tocar fidelización — que es exactamente por qué esto es un contexto aparte                               |

## El problema hoy

Los datos de clientes de una empresa están repartidos entre un punto de venta, un ecommerce, un
sistema de facturación y una planilla, y la misma persona existe en cada uno con una llave distinta.
Cada herramienta de engagement construye entonces su propia copia a medio resolver, y las respuestas
no coinciden.

ADR-009 plantea el argumento estructural: si perfiles, eventos y segmentos viven dentro de
fidelización, el día que un segundo módulo necesite un segmento hay que refactorizar fidelización
para obtenerlo. Construir el núcleo primero cuesta un contexto acotado más que gobernar y regala
todos los módulos futuros.

Hay un segundo problema, más filoso y específico de Latinoamérica. La identidad aquí es un documento
—RUT, CPF, CUIT, CC— con formato, dígito verificador y estatus legal distintos por país, y que
identifica tanto a personas como a empresas. Las herramientas construidas afuera modelan un cliente
como una persona con un email. Ese desajuste es un diferenciador real, no un detalle de
localización.

## Qué hace *(normativo)*

* Guarda **contactos** que pueden ser persona o empresa (DEC-A1), cada uno con un documento
  opcionalmente validado para su país y tipo.
* **Resuelve identidad**: un visitante anónimo se vuelve un contacto conocido, los duplicados entre
  sistemas convergen, y las fusiones quedan registradas.
* Registra el **consentimiento como historia**, por canal, con prueba y timestamp — nunca como un
  flag mutable.
* Ingiere **eventos de comportamiento** por una API pública que responde en menos de 100 ms y
  procesa de forma asíncrona.
* Evalúa **segmentos** desde un DSL declarativo, incrementalmente, para que los cambios de membresía
  emitan eventos casi en tiempo real.
* Entrega **taxonomías verticales de eventos como datos instalables**, para que un negocio de
  suscripción y un retail partan con un vocabulario que les calce (DEC-H7).
* Es dueño de las **tablas de plataforma** que todo módulo necesita: auditoría, snapshots de
  consumo, jobs procesados, dead letters y los catálogos transversales.
* Ejecuta **supresión y portabilidad**, para que toda la suite honre los derechos del titular desde
  un solo lugar.

## Lo que NO hace *(normativo)*

* **No es un CDP.** Sin sincronización con warehouse, sin reverse ETL, sin catálogo arbitrario de
  destinos. Ingerimos, resolvemos, segmentamos y emitimos — esa es toda la superficie.
* **No es una herramienta de marketing.** Core calcula un segmento; enviarle algo es `messaging`.
* **No es un espacio de atención al cliente.** Notas, actividades y timeline son `crm`.
* **Ninguna fusión automática sin evidencia.** Las importaciones masivas producen una cola de
  revisión, nunca una fusión silenciosa (DEC-A6). Una fusión equivocada es casi irrecuperable.
* **No es multi-región en F1.** La costura `cell_id` existe; enrutar tenants entre celdas no.

## Éxito

| Medida                                                                    | Objetivo                                                | Para                            |
| ------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------- |
| `track` p95                                                               | \<100 ms (fast-ack 202)                                 | certificación, pre-G1           |
| Evento hasta cambio de membresía de segmento                              | \<5 s p95                                               | certificación, pre-G1           |
| Corrección de resolución de identidad sobre un set sembrado de duplicados | cero fusiones falsas                                    | antes de G1                     |
| Cobertura de validación de documentos                                     | todo país sudamericano con algoritmo de DV implementado | G1-Engage                       |
| Solicitud de supresión ejecutada end to end                               | ≤30 días, totalmente automatizada, cero pasos manuales  | antes del lanzamiento comercial |

## Modelo comercial

Core define la base facturable de toda la suite: el **contacto accionable** (ADR-014). También
produce `usage_snapshots` cada 30 minutos (DEC-G1), que es desde donde factura el rating engine y lo
que lee el panel de consumo.

Nunca se vende solo. Sus capacidades se gatean indirectamente: tiers de retención sobre
`tracked_events`, add-on de frescura de datos sobre el recálculo completo de segmentos.

## Fases

| Fase    | Contenido                                                                                                                                                                                                      | Objetivo              |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **F1a** | Catálogos de plataforma · contactos y documentos · resolución de identidad · consentimientos · pipeline de ingesta · DSL de segmentos v1 · auditoría · infraestructura de jobs · snapshots de consumo          | G1-Engage, 2026-11-01 |
| **F1b** | Definiciones de atributos personalizados · importación CSV con revisión de fusiones · taxonomías de eventos · write keys públicas para ingesta desde el navegador · automatización de supresión y portabilidad | post-G1               |
| **F2**  | Enrutamiento multi-región por celdas · capa de compatibilidad Segment si una integración real la exige                                                                                                         | 2027                  |

## Cumplimiento y riesgo

Core es donde se concentra la exposición regulatoria de la suite: contiene los datos personales, el
registro de consentimiento y el rastro de auditoría. Tres obligaciones condicionan el diseño en vez
de acompañarlo.

* **El consentimiento es una entidad, no una columna.** Cada otorgamiento y cada revocación es una
  fila con prueba y timestamp, porque la Ley 21.719 fiscaliza evidencia, no políticas.
* **El documento de identidad es el campo más sensible de la plataforma.** Enmascarado por defecto
  en todas partes, valor completo tras un permiso dedicado, cada lectura completa auditada (DEC-A4).
  Rige la legislación más estricta entre los países soportados.
* **La supresión se orquesta aquí.** Core borra el perfil y sus eventos, e instruye a fidelización a
  anonimizar en vez de destruir su libro (DEC-J3). Ningún otro módulo decide esto por su cuenta.

El riesgo técnico principal es la resolución de identidad: una fusión falsa combina dos personas
reales, y deshacerla es casi imposible. Toda decisión de diseño aquí se inclina a negarse a fusionar
cuando hay incertidumbre.

## Dependencias

Particionamiento de Postgres para `tracked_events` (ADR-018). Better Auth para ambos realms
(ADR-010). Upstash para rate limiting y la caché de segmentos compilados. `QueuePort` para el
pipeline de ingesta. Core no depende de **ningún otro contexto acotado**, y eso se verifica.

## Preguntas abiertas

| # | Pregunta                                                                                                                   | Decide | Para                          |
| - | -------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------- |
| 1 | ¿Qué taxonomía vertical se entrega segunda, después de suscripciones y servicios?                                          | Daniel | antes de FS-CORE-0012         |
| 2 | ¿El historial de eventos de un visitante anónimo sobrevive si nunca se vuelve conocido, o se purga con un reloj más corto? | Daniel | antes de aprobar FS-CORE-0006 |

## Changelog

| Versión | Fecha      | Cambio                                                                | Por qué | Autor                  |
| ------- | ---------- | --------------------------------------------------------------------- | ------- | ---------------------- |
| 0.1.0   | 2026-08-17 | Borrador inicial desde el registro de decisiones y el spec del módulo | —       | daniel + claude-opus-5 |