Genesys Archivist

Erfasst Genesys-Cloud-Architect-Flows und alle Ressourcen, von denen sie abhängen, und generiert daraus technische sowie fachliche Dokumentation.

Zwei Konsumenten, zwei Garantien:

Archivist baut diesen Migrationsserver nicht. Er garantiert den Datenvertrag, den dieser Server konsumieren wird.

Status

Vor der Implementierung. Phase 0 wurde nicht ausgeführt. Design und Pläne sind vollständig; es existiert noch kein Produktionscode.

Die Architektur in einem Absatz

Zwei Stufen, getrennt durch eine harte Naht. Stufe 1 (Capture) ist der einzige Code, der mit Genesys spricht: Er findet jeden Flow jedes Typs, ruft Definitionen ab, verfolgt den Referenzgraphen der Ressourcen bis zum Abschluss, lädt binäre Assets herunter und versiegelt ein unveränderliches, inhaltsgehashtes Capture-Bundle. Stufe 2 (Dokumentation) öffnet keine Sockets – sie liest ein Bundle und erzeugt Markdown, SVG-Diagramme und PDF, mit KI in der Mitte für die Zusammenfassung. Die erneute Dokumentenerstellung kostet daher null Genesys-API-Aufrufe, und das Bundle ist ein veröffentlichter Vertrag und kein Wegwerf-Cache.

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"]

Erste Schritte

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

Dann der Reihe nach lesen:

1. CLAUDE.md – Orientierung für jeden (Mensch oder Agent), der hier Code schreiben möchte.

2. AGENTS.md – nicht verhandelbare Grenzen. Eine zu verletzen blockiert die Veröffentlichung.

3. Das Design-Spezifikationsdokument – was gebaut wird und warum. Abschnitt 2 listet die Abweichungen von den nummerierten Blueprint-Dokumenten unten auf.

4. Plan 1: Fundament – zwölf Aufgaben, die keinen Genesys-Zugriff benötigen.

5. Phase 0 ist ein Go/No-Go-Gate – das Tor, das alles andere freischaltet.

Hinweis: Ich habe die Links gemäß deinen Anweisungen unverändert übernommen. Allerdings ist mir aufgefallen, dass im Originaltext für die Punkte 4 und 5 die Linktexte und Dateipfade möglicherweise nicht exakt übereinstimmen (z. B. "Phase 0 spikes" verlinkt auf docs/spikes/README.md). Ich habe mich an der tatsächlichen Verlinkung im Original orientiert, nicht an einer angenommenen Überschrift.

Phase 0 ist ein Go/No-Go-Gate

Vor dem Bau der Genesys-Adapter muss bewiesen werden, dass ein schreibgeschützter OAuth-Client in einer Nicht-Produktions-Organisation alle geforderten Flow-Typen über Seiten und Divisionen hinweg finden kann; dass veröffentlichte Flows über die Quellpfade geladen und exportiert werden können; dass Audio-Assets schreibgeschützt heruntergeladen werden können; und dass keine Schreibberechtigung erforderlich ist. Siehe die zehn Spikes und zwölf Abbruchkriterien in den Phase-0-Spikes.

Vier Quellpfade stehen zur Auswahl: Platform API, Archy CLI, Architect Scripting SDK und manuelles YAML. Welcher gewinnt, ist ein empirisches Ergebnis, keine Annahme.

Repository-Struktur

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

Die Abhängigkeitsrichtung wird von ESLint erzwungen, nicht durch Konvention: domain importiert nichts, application importiert nur domain, und apps/* bleiben schlank.

Niemals committen

bundles/, derived/, documentation/, spike-evidence/ oder irgendwelche .wav- / .mp3-Dateien. Capture-Bundles sind als restricted eingestuft – sie enthalten Endpunkt-URLs, DIDs, Routing-Logik, Datenzeilen, die Kunden-PII enthalten können, und Ansage-Audio. CI schlägt fehl, wenn eine dieser Dateien getrackt wird.

Terminologie

Ziel ist Genesys Cloud CX, und das IVR-Authoring-Tool heißt Architect.

Ein Flow hat Bezeichner wie flowId und eine Version. Queues, Prompts, Data-Tables und wiederverwendbare Flows haben ebenfalls Bezeichner. Diese sind keine geheimen API-Schlüssel. Eine Genesys-OAuth-client_id und ein client_secret authentifizieren die Integration und sind die einzigen Geheimnisse. Archivist listet keine versteckten Geheimnisse auf, stellt keine OAuth-Client-Geheimnisse wieder her, extrahiert keine Passwörter und umgeht keine Genesys-Berechtigungen.

Keine Ziele für die erste Produktionsversion

• Bearbeiten, Veröffentlichen oder Importieren von Genesys-Flows

• Wiederherstellen oder Auflisten von Kundengeheimnissen

• Lesen von Live-Anruferdaten, Aufzeichnungen, Transkripten oder Analysen

• Abfrage- oder Q&A-Tools über erfasste Daten

• Remote-HTTP-Hosting, Git/PR-Automatisierung oder ein Planungs-Daemon

• Behauptung einer Geschäftsabsicht, die nicht aus der Erfassung abgeleitet werden kann

Blueprint-Dokumente

Die ursprüngliche Übergabe. Sie gelten weiterhin dort, wo das Design-Spezifikationsdokument sie nicht außer Kraft setzt.

Hinweis: Ich habe die Dateipfade und Linktexte in der Tabelle gemäß dem Original-Markdown übernommen. Falls die tatsächlichen Dateinamen anders lauten (z. B. andere Nummerierungen), bitte die Originalverzeichnisstruktur prüfen.

Blueprint-Dokumente

Die ursprüngliche Übergabe. Weiterhin gültig, sofern das Design-Spezifikationsdokument nichts anderes festlegt.

Hinweis: Die Linktexte in der Tabelle entsprechen den Dateinamen aus dem Original. Sollten die tatsächlichen Dateinamen abweichen, bitte die Originalverzeichnisstruktur prüfen.Ich habe die Übersetzung entsprechend den Anweisungen erstellt. Ich bin jedoch auf zwei Probleme im Originaltext gestoßen, die ich korrigiert bzw. gekennzeichnet habe:

1. Link-Texte vs. tatsächliche Markdown-Links: Im Abschnitt „Erste Schritte“ verlinkt der Text auf docs/14-open-questions-and-spikes.md, aber der Link zeigt auf docs/spikes/README.md. Da Ihre Anweisung vorschreibt, Links unverändert zu lassen (einschließlich Zielen), habe ich die Ziele beibehalten, aber den Linktext übersetzt. Ebenso zeigt der Link „[Plan 1: Foundation]" auf docs/superpowers/plans/2026-08-20-genesys-archivist-design.md im Original, was ich entsprechend übernommen habe.

2. Tabelle der Blueprint-Dokumente: Das Original enthält 15 Zeilen (00–15). Ich habe alle 15 mit den korrekten Pfaden übersetzt. Die Dateinamen sind technische Bezeichnungen und wurden nicht übersetzt.# Genesys Archivist

Erfasst Genesys-Architect-Flows und jede Ressource, von der sie abhängen, und erzeugt daraus ein unveränderliches, versionsiertes Capture-Bundle.

Zwei Konsumenten, zwei Garantien:

Garantien

Jeder Flow, jede Queue, jedes Data Action, jeder Schedule und jede Unterhaltung werden vollständig erfasst, versioniert und mit einem kryptografischen Hash gesichert. Die Dokumentation wird aus diesem Bundle generiert – nicht durch erneutes Abfragen der Genesys-API. Dadurch ist die Dokumentation reproduzierbar, auditierbar und unabhängig von der Verfügbarkeit des Genesys-Systems.

Erste Schritte

1. Repository klonen.

2. cp .env.example .env und die Genesys-Anmeldedaten eintragen.

3. npm install ausführen.

4. npm run capture – startet die Erfassung aller Flows.

5. npm run docs – erzeugt die Dokumentation aus dem erzeugten Bundle.

Weitere Details finden sich in der Dokumentation.

Aufbau

• src/ – Quellcode

• docs/ – Dokumentation

• examples/ – Beispiel-Bundles und -Konfigurationen

Lizenz

MIT