> **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 de la solución móvil

Super App es una aplicación cliente para iOS y Android. Su contenedor usa
React Native, Expo, TypeScript, Expo Router y Zustand. La distribución móvil y
la ejecución de los servicios externos pertenecen a sus respectivos owners; el
proyecto no añade un servidor propio, un microservicio ni una base de datos de
negocio.

## Modelo de sistemas

```mermaid
flowchart TD
    device["Cliente iOS / Android"]
    device --> app["Contenedor Super App"]
    app --> ia["Naturgy IA"]
    app --> mi["Mi Naturgy"]
    app --> today["Al día"]
    app --> transversal["Servicios transversales"]

    ia --> chat["Chat HappyRobot"]
    ia --> webvoice["Voz WebRTC / Chime"]
    webvoice --> connect["Amazon Connect"]
    chat --> workflows["Workflows y especialistas"]
    connect --> workflows

    mi --> omega["Omega WebView"]
    today --> aem["AEM"]
    today --> weather["NAPAI / Mulesoft"]
    transversal --> firebase["Firebase / GA4 / Crashlytics"]
    transversal --> consent["OneTrust"]
    transversal --> ota["EAS Update"]
```

La app coordina la experiencia, pero los servicios externos mantienen la
identidad, los datos, las conversaciones, los casos y el contenido. Una
integración dibujada en este mapa no implica que tenga todos sus permisos,
ambientes o contratos cerrados.

## Módulos

| Módulo | Tecnología o servicio | Propósito |
|---|---|---|
| Contenedor y navegación | React Native, Expo Router, TypeScript, Zustand | Arranque, navegación, estado de interfaz e internacionalización. |
| Naturgy IA — chat | SDK/API de HappyRobot | Crear o continuar conversaciones de texto y recibir respuestas. |
| Naturgy IA — voz | Amazon Connect, Chime/WebRTC y gestor de llamada | Iniciar audio, conservar el contexto de llamada y transferir cuando corresponde. |
| Mi Naturgy | WebView de Omega y visor PDF nativo | Login, facturas, contratos, datos y documentos. |
| Al día | AEM y NAPAI/Mulesoft | Contenido editorial, municipios y meteorología. |
| Sesión y onboarding | Omega y biometría local opcional | Mantener la sesión y facilitar el acceso local al dispositivo. |
| Notificaciones | Firebase Messaging y Marketing Cloud | Recibir notificaciones push. |
| Analítica y errores | Firebase Analytics/GA4/GTM, Crashlytics y Quantum | Eventos, errores y métricas, sujetos a consentimiento y minimización. |
| Consentimiento | OneTrust CMP | Recoger y propagar preferencias a las superficies que lo necesitan. |
| Configuración y OTA | Firebase Remote Config y Expo EAS Update | Feature flags, kill switches, textos y actualización del bundle JavaScript. |

## Separación de datos

La app mantiene solo estado de cliente necesario para la experiencia:

* **SecureStore:** credenciales y tokens que el contrato permita guardar;
* **AsyncStorage:** preferencias y caché ligera;
* **Zustand:** estado efímero de interfaz.

Los maestros viven fuera de la app: Omega mantiene identidad, contratos,
facturas y documentos; Salesforce/Carolina o Mulesoft mantienen casos y
gestiones; HappyRobot/Connect/Twin mantienen conversación y ejecución según su
configuración; AEM y NAPAI mantienen contenido y meteorología.

El token de sesión de Omega no debe confundirse con una credencial técnica de
la aplicación. Un `user_id`, un atributo de Connect o una instrucción del prompt
no autorizan por sí solos una consulta de negocio.

## Entornos

La solución separa perfiles de desarrollo, preview y producción tanto en la
app como en los workflows. Cada perfil debe usar sus propios endpoints,
números, credenciales, flags y datos de prueba. No se debe cruzar PRE/PRO en
runtime ni usar un snapshot de una versión editable como prueba de producción.

La app puede distribuir builds mediante stores y actualizaciones OTA, pero la
existencia de una configuración de build no demuestra que la aplicación esté
lanzada públicamente. El estado de publicación debe confirmarse con el owner de
la app.

## ATC modular para Super App

La propuesta para llevar ATC de voz a Super App usa un workflow callable separado
del workflow telefónico live. El shell recibe el handoff, llama a Auth y Triaje,
y el triaje invoca un child por capacidad. `transfer_chain` permanece compartido
y Post-call centraliza el cierre.

```mermaid
flowchart TD
    dispatcher["Dispatcher"] --> shell["ATC SuperApp Modular<br/>shell callable"]
    shell --> auth["Auth"]
    auth --> triage["Triaje"]
    triage --> specialists["Especialista de capacidad"]
    specialists -->|"completado / volver"| post["Post-call"]
    specialists -->|"escalar / transferir"| transfer["transfer_chain"]
    transfer --> post
    post --> systems["Salesforce / Twin / observabilidad"]
```

Esta es una arquitectura **to-be** implementada en drafts no publicados; no
convierte el Dispatcher en multicanal ni habilita ATC texto. Operaciones sigue
el mismo patrón con un parent, un adapter de Auth, triaje, cuatro children de
dominio y Post-call. La modularidad sustituye los saltos internos
`module-change` por Workflow Functions, conserva las tools acotadas por
especialista y exige response nodes, timeouts y payloads explícitos. Consulta
[el inventario de implementaciones modulares](/use-cases/super-app/reference/modular-implementations)
y [la referencia del plan de ATC](/use-cases/super-app/reference/atc-modular-plan)
para la topología, los contratos y los gates.

## Resiliencia

La pérdida de conectividad se detecta desde el dispositivo. Timeouts o errores
504 de Omega, AEM o NAPAI deben mostrar un estado recuperable y permitir reintentar
sin duplicar operaciones. Remote Config puede bloquear una superficie o exigir
una versión mínima, pero no sustituye los controles del backend.

Para entender qué datos viajan entre estos módulos, consulta [Integraciones y
ciclo CI/CG](/use-cases/super-app/explanations/integrations). Para el modelo de
acceso, consulta [Seguridad y acceso](/use-cases/super-app/explanations/security).