> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Arquitectura modular de ATC para Super App

El plan modular separa el ATC de Super App del workflow telefónico existente.
Su objetivo es conservar la paridad funcional de voz y sustituir los saltos
internos `module-change` por llamadas estructuradas entre workflows hijos.

**Estado:** propuesta implementada en drafts no publicados. No modifica ni
publica el workflow live de telefonía. La ruta de texto queda fuera de la
paridad inicial mientras el Dispatcher y ATC texto no tengan un contrato
aprobado. Para comparar el inventario y la evidencia con la implementación
modular de Operaciones, consulta [Implementaciones modulares de Operaciones y
ATC](/use-cases/super-app/reference/modular-implementations).

## Topología propuesta

```mermaid
flowchart TD
    dispatcher["Dispatcher de Super App"] -->|"route handoff"| shell["ATC SuperApp Modular<br/>shell callable"]
    shell --> auth["ATC Auth<br/>child reutilizado"]
    auth --> triage["ATC Triaje"]
    triage --> billing["Dudas Facturas"]
    triage --> payments["Pagos"]
    triage --> installments["Fraccionamiento"]
    triage --> products["Comparativa y producto"]
    triage --> data["Cambio de datos"]
    triage --> readings["Lecturas"]
    triage --> copies["Duplicados"]
    triage --> supply["Sin suministro"]
    triage --> ownership["Cambio de titular"]
    billing --> back["RETURN_TO_TRIAGE"]
    payments --> back
    installments --> back
    products --> back
    data --> back
    readings --> back
    copies --> back
    supply --> back
    ownership --> back
    back --> triage
    shell --> transfer["transfer_chain existente"]
    billing --> post["ATC Post-call"]
    payments --> post
    installments --> post
    products --> post
    data --> post
    readings --> post
    copies --> post
    supply --> post
    ownership --> post
    transfer --> post
    post --> systems["Salesforce / Twin / observabilidad"]
```

Los nueve especialistas siguen siendo workflows hijos separados. `transfer_chain`
se conserva como workflow compartido y no se duplica en cada especialista.

## Responsabilidad de cada pieza

| Pieza | Tipo de entrada | Responsabilidad | Salida |
|---|---|---|---|
| Shell ATC | `Workflow Function Request` | Recibir la conversación, preparar contexto, llamar Auth y Triaje, y coordinar Post-call. | Resultado estructurado del flujo. |
| Auth | `Workflow Function Request` | DNI/NIE/CIF, ANI, OTP, ficha y estado de autenticación. | Respuesta de autenticación saneada. |
| Triaje | `Workflow Function Request` | Clasificar intención y elegir un especialista; no ejecuta la gestión. | Resultado del especialista o continuación. |
| Especialista | `Workflow Function Request` | Mantener prompt, tools y reglas de una única capacidad. | `COMPLETED`, `RETURN_TO_TRIAGE`, `ESCALATED` o `FAILED`. |
| Post-call | `Predefined Request` | Procesar cierre, extracción, Salesforce, Twin y estado de escalado. | Estado terminal del cierre. |
| `transfer_chain` | Workflow compartido | Gestionar el cierre posterior de una transferencia. | Resultado del pase y contexto de cierre. |

Cada child conversacional debe ser callable y compatible con la llamada del
parent. Su response node debe estar declarado y todos los caminos terminales
deben respetar el mismo contrato.

## Qué cambia respecto al workflow monolítico

El workflow de ATC de voz actual contiene OTP, triaje y especialistas conectados
por `module-change`. La propuesta modular:

* conserva los playbooks y las tools de cada capacidad inicialmente;
* mueve Auth, Triaje, especialistas y Post-call a límites de workflow;
* convierte cada cambio de módulo en un `Call Workflow`;
* devuelve `RETURN_TO_TRIAGE` al parent en lugar de saltar a un prompt vecino;
* mantiene el camino corto de pago cuando un especialista lo necesita;
* deja la transferencia en `transfer_chain` y en Connect;
* permite probar cada child de forma aislada antes de ejecutar el flujo completo.

No se debe copiar todo el workflow en un único prompt ni hacer visibles todas
las tools a todos los especialistas. La frontera modular existe precisamente
para conservar el contexto y limitar la superficie de cada capacidad.

## Contratos parent/child

Los campos que deben declararse explícitamente dependen del salto:

### Dispatcher → shell

```text
channel, source, correlation_id, session_id,
parent_run_id, user_id o referencia mínima, token_id,
intent, subintent, confidence, summary, language,
environment y caso existente si ya está autorizado
```

No se pasan API keys, Bearer tokens, transcript completo, IBAN ni documento
completo para clasificar. El Dispatcher actual no demuestra todavía que este
envelope llegue al target; es un gate pendiente.

### Shell/Triaje → especialista

```text
parent_run_id, correlation_id, session_id, channel,
intent, subintent, confidence, summary,
auth, estado de autenticación, ficha y elegibilidad mínimas
```

La respuesta debe indicar si la gestión terminó, vuelve a triaje, escala o
falló. Un prompt parent no debe adivinar el estado a partir de texto libre.

### Shell → Post-call

```text
parent_run_id, parent_version_id, parent_environment,
correlation_id, session_id, caso,
resultado de autenticación, señales de handoff,
transcript o referencia autorizada y variables de cierre
```

El child tiene sus propios `current.run_id`, `current.version_id` y
`current.execution_environment`. Por eso `parent_run_id`, versión, entorno y
correlación deben conservarse explícitamente para no atribuir el cierre al run
hijo equivocado.

## Post-call y observabilidad

El Post-call distingue dos ramas:

* **Hubo escalado:** guarda el estado mínimo de la transferencia y termina sin
  inventar un nuevo motivo de enrutado.
* **No hubo escalado:** extrae resumen e intención, actualiza el caso y escribe
  observabilidad según el contrato.

La implementación propuesta debe mantener la relación entre parent, children,
Connect, Salesforce y Twin. Un error de transcript, un response vacío o un
child que pierde correlación debe quedar como fallo observable, no como un
cierre aparentemente correcto.

## Reglas de configuración

Antes de activar una llamada entre workflows, comprueba:

* target y entorno explícitos;
* `use_caller_environment` cuando el parent y los children deban permanecer en
  el mismo perfil;
* trigger callable y `Call compatible` del child;
* response node real y persistente;
* parámetros declarados y payload que coincide con el schema;
* timeout y manejo explícito de `FAILED`/`TIMEOUT`;
* referencias remapeadas al identificador persistente del nodo productor;
* ausencia de credenciales o PII real en prompts, pruebas y exports.

Un timeout del child no garantiza que su ejecución se cancele. El parent debe
impedir que el modelo continúe con datos incompletos y aplicar el fallback
aprobado.

## Estado y gates

Esta arquitectura no demuestra una ruta disponible para clientes. Antes de
conectarla al Dispatcher se necesita:

* verificar que el baseline de ATC voz sigue siendo la fuente correcta;
* validar Auth, Triaje, cada especialista y Post-call en el entorno de prueba;
* comprobar response nodes, permisos y contratos de cada child;
* ejecutar UCD/E2E con autenticación, retorno a triaje, escalado y errores;
* conservar `parent_run_id` en proxy, Connect y Twin;
* comprobar que `transfer_chain` y la grabación no se duplican;
* decidir el destino de ATC texto por separado;
* obtener aprobación de Producto, Negocio, Seguridad y owners técnicos.

No se debe promover un draft, utilizar el latest como baseline ni cambiar el
workflow telefónico live para probar esta arquitectura.

Consulta [Dispatcher y enrutado](/use-cases/super-app/explanations/dispatcher),
[Inventario de workflows](/use-cases/super-app/reference/workflows) y
[Evidencia, UAT y pendientes](/use-cases/super-app/reference/evidence).