How mahmouddattiaa/genesys-archivist works
Genesys Archivist captures Genesys Cloud Architect flows and their dependent resources into an immutable, content-hashed bundle, then documents that bundle without making further Genesys calls. Users enter through the CLI or MCP server; the application/composition layer coordinates profiles, capture, and documentation. Capture has distinct discovery, resource-resolution, and bundle-writing responsibilities. Documentation normalizes captured configuration, analyzes it, builds evidence-grounded narration, and emits Markdown and diagrams, with rendering as a separate optional step. The README documents these capabilities; some subsystem links are therefore documented rather than verified in sampled implementation excerpts.
Main entry points: archivist-port.ts Archivist service · document-bundle-to-disk.ts Documentation pipeline · capture-run.ts Capture runner · platform-source-provider.ts Genesys source adapter
Components 25
User interfaces
- Archivist CLI
apps/cli/src/bin.ts - Profile commands
apps/cli/src/commands/profile.ts - MCP server
apps/mcp-server/src/server.ts - Flow-list tool
apps/mcp-server/src/tools/flows-list.ts
Application orchestration
- Application planning
packages/application/src/plan.ts - Archivist service
packages/composition/src/archivist-port.ts - Run state
packages/application/src/run-state-machine.ts - Profile storage
packages/storage/src/profile-store.ts
Capture and platform
- Capture runner
packages/capture/src/capture-run.ts - Resource graph
packages/capture/src/resource-graph.ts - Sealed bundle
packages/capture/src/bundle-writer.ts - Genesys source adapter
packages/genesys-source/src/platform-source-provider.ts - Resource readers
packages/genesys-source/src/resource-readers.ts - Read-only API client
packages/genesys-platform/src/client.ts
Analysis and narration
- Flow normalization
packages/normalization/src/normalize.ts - Node extraction
packages/normalization/src/extract-nodes.ts - Edge extraction
packages/normalization/src/extract-edges.ts - Flow analysis
packages/analysis/src/diff.ts - Evidence pack
packages/narrative/src/evidence-pack.ts - AI narration
packages/narrative/src/narration-provider.ts
Documentation outputs
- Documentation pipeline
packages/composition/src/document-bundle-to-disk.ts - Markdown and diagrams
packages/composition/src/render-narrative.ts - Diagram renderer
packages/rendering/src/playwright-renderer.ts - PDF output
packages/rendering/src/renderer.ts
Other components
- Genesys Cloud
Connections 26
- Archivist CLI → Archivist service: invokes services
apps/cli/src/bin.ts - Profile commands → Archivist service: configures profiles
- MCP server → Flow-list tool: registers tool
apps/mcp-server/src/server.ts - Flow-list tool → Archivist service: requests flow list
apps/mcp-server/src/tools/flows-list.ts - MCP server → Application planning: serves plans
- Application planning → Archivist service: plans operations
packages/application/src/plan.ts - Archivist service → Run state: tracks runs
- Archivist service → Profile storage: reads profiles
- Archivist service → Capture runner: runs capture
packages/composition/src/archivist-port.ts - Capture runner → Genesys source adapter: fetches source
- Genesys source adapter → Resource readers: resolves resources
packages/genesys-source/src/platform-source-provider.ts - Resource readers → Read-only API client: requests resource data
packages/genesys-source/src/resource-readers.ts - Genesys source adapter → Read-only API client: uses API client
packages/genesys-source/src/platform-source-provider.ts - Read-only API client → Genesys Cloud: sends GET requests
README.md - Capture runner → Resource graph: walks dependencies
packages/capture/src/capture-run.ts - Capture runner → Sealed bundle: writes bundle
packages/capture/src/capture-run.ts - Sealed bundle → Documentation pipeline: provides capture
README.md - Documentation pipeline → Flow normalization: normalizes flows
- Flow normalization → Node extraction: extracts nodes
packages/normalization/src/normalize.ts - Flow normalization → Edge extraction: extracts edges
packages/normalization/src/normalize.ts - Documentation pipeline → Flow analysis: analyzes flows
- Documentation pipeline → Evidence pack: builds evidence
- Evidence pack → AI narration: grounds narration
- Documentation pipeline → Markdown and diagrams: writes documentation
README.md - Documentation pipeline → Diagram renderer: optionally renders
README.md - Diagram renderer → PDF output: produces PDF
packages/rendering/src/playwright-renderer.ts