Genesys Archivist

Captura los flujos de Genesys Cloud Architect y todos los recursos de los que dependen, y luego genera documentación técnica y de negocio a partir de esa captura.

Dos consumidores, dos garantías:

Archivist no construye ese servidor de migración. Garantiza el contrato de datos que ese servidor consumirá.

Estado

Pre-implementación. La fase 0 no se ha ejecutado. El diseño y los planes están completos; aún no existe código de producción.

La arquitectura en un párrafo

Dos etapas separadas por una frontera rígida. La etapa 1 (captura) es el único código que habla con Genesys: descubre todos los flujos de todos los tipos, obtiene las definiciones, recorre el grafo de referencia de recursos hasta el cierre, descarga los recursos binarios y sella un paquete de captura inmutable con hash de contenido. La etapa 2 (documentación) no abre sockets: lee un paquete y produce Markdown, diagramas SVG y PDF, con narración de IA en el medio. Por lo tanto, volver a renderizar la documentación no cuesta ninguna llamada a la API de Genesys, y el paquete es un contrato publicado, no una caché desechable.

flowchart TD
    A["AI client"] -->|MCP STDIO| B["MCP adapter"]
    C["archivist CLI"] --> D["Application service"]
    B --> D
    D --> E["Genesys source provider"]
    E --> F["Genesys Cloud"]
    D --> G["Capture bundle (sealed, immutable)"]
    G --> H["Normalize, analyze, document"]
    H --> I["Markdown + diagrams + PDF"]
    G --> J["Future migration server"]

Primeros pasos

npm install
npm run verify        # format + lint + typecheck + test + schema validation

Luego lee, en orden:

1. CLAUDE.md — orientación para cualquiera (humano o agente) que vaya a escribir código aquí.

2. AGENTS.md — límites innegociables. Violar uno es un bloqueo de lanzamiento.

3. La especificación de diseño — qué se está construyendo y por qué. La sección 2 enumera las desviaciones de los documentos de planificación numerados a continuación.

4. Plan 1: Fundación — doce tareas TDD paso a paso que no requieren acceso a Genesys.

5. Experimentos de la fase 0 — la puerta go/no-go que desbloquea todo lo demás.

La fase 0 es una puerta go/no-go

Antes de construir los adaptadores de Genesys, se debe demostrar contra una organización que no sea de producción que un cliente OAuth de solo lectura puede enumerar todos los tipos de flujo requeridos a través de páginas y divisiones; que una ruta de origen puede cargar y exportar flujos publicados de forma fiel; que las descargas de audio de los mensajes son de solo lectura; y que no se requiere ningún permiso de mutación. Diez experimentos, doce criterios de cancelación. Consulte docs/spikes/.

Hay cuatro rutas de origen en disputa: la API de Platform, la CLI de Archy, el SDK de Architect Scripting y YAML manual. Cuál gana es un resultado empírico, no una suposición.

Estructura del repositorio

apps/cli               archivist CLI
apps/mcp-server        genesys-archivist MCP STDIO server
packages/domain        contracts and DTOs. Pure: no I/O, no SDK types
packages/application   use cases, run state machines, policy
packages/composition   the one place adapters are wired to interfaces
packages/...           adapters, capture, analysis, documentation, rendering, narrative
schemas/               versioned JSON Schema contracts
fixtures/              sanitized test fixtures. Never real customer configuration
docs/                  blueprint, design spec, plans, ADRs, spikes

La dirección de las dependencias se aplica mediante ESLint, no por convención: domain no importa nada, application importa solo domain, y apps/* se mantienen delgados.

No comprometer nunca

bundles/, derived/, documentation/, spike-evidence/, ni ningún .wav o .mp3. Los paquetes de captura están clasificados como restringidos: contienen URLs de endpoints, DIDs, lógica de enrutamiento, tablas de datos que pueden contener PII de clientes y audio de mensajes. CI falla la compilación si alguno de estos está bajo seguimiento.

Terminología

El producto es Genesys Cloud CX, y el producto de autoría de IVR es Architect.

Un flujo tiene identificadores como flowId y una versión. Las colas, los mensajes, las acciones de datos, los horarios y los flujos reutilizables también tienen identificadores. Estos no son claves de API secretas. Un client_id y client_secret de OAuth de Genesys autentican la integración y son los únicos secretos involucrados. La herramienta nunca enumera secretos ocultos, recupera secretos de cliente OAuth, extrae contraseñas ni elude los permisos de Genesys.

No objetivos para la primera versión de producción

• Editar, publicar, importar o eliminar flujos de Genesys

• Recuperar o enumerar secretos de clientes

• Leer datos de llamadas en vivo, grabaciones, transcripciones o datos de ejecución históricos

• Herramientas de consulta o preguntas y respuestas sobre los datos capturados

• Alojamiento HTTP remoto, automatización de git/PR o un daemon de programación

• Reclamar intención de negocio que no se pueda inferir de la configuración

Documentos de planificación

El borrador original. Sigue siendo de aplicación en todo lo que la especificación de diseño no anule.