# mahmouddattiaa/genesys-archivist architecture

> Architecture diagram of the GitHub repository mahmouddattiaa/genesys-archivist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahmouddattiaa/genesys-archivist
- Repository: https://github.com/mahmouddattiaa/genesys-archivist

## Overview

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: [`packages/composition/src/archivist-port.ts`](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/composition/src/archivist-port.ts) (Archivist service), [`packages/composition/src/document-bundle-to-disk.ts`](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/composition/src/document-bundle-to-disk.ts) (Documentation pipeline), [`packages/capture/src/capture-run.ts`](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/capture/src/capture-run.ts) (Capture runner), [`packages/genesys-source/src/platform-source-provider.ts`](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/genesys-source/src/platform-source-provider.ts) (Genesys source adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Archivist CLI<br/>[bin.ts]"]
  node_profiles["Profile commands<br/>[profile.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_flowtools["Flow-list tool<br/>[flows-list.ts]"]
end

subgraph group_orchestration["Application orchestration"]
  node_application["Application planning<br/>[plan.ts]"]
  node_composition["Archivist service<br/>[archivist-port.ts]"]
  node_runstate["Run state"]
  node_profile_store[("Profile storage<br/>[profile-store.ts]")]
end

subgraph group_capture["Capture and platform"]
  node_capture["Capture runner<br/>[capture-run.ts]"]
  node_resourcegraph["Resource graph<br/>[resource-graph.ts]"]
  node_bundle[("Sealed bundle<br/>[bundle-writer.ts]")]
  node_provider["Genesys source adapter"]
  node_readers["Resource readers"]
  node_platform["Read-only API client<br/>[client.ts]"]
end

subgraph group_knowledge["Analysis and narration"]
  node_normalization["Flow normalization<br/>[normalize.ts]"]
  node_extractnodes["Node extraction<br/>[extract-nodes.ts]"]
  node_extractedges["Edge extraction<br/>[extract-edges.ts]"]
  node_analysis["Flow analysis<br/>[diff.ts]"]
  node_evidence["Evidence pack<br/>[evidence-pack.ts]"]
  node_narration["AI narration"]
end

subgraph group_outputs["Documentation outputs"]
  node_document["Documentation pipeline"]
  node_markdown["Markdown and diagrams"]
  node_renderer["Diagram renderer"]
  node_pdf["PDF output<br/>[renderer.ts]"]
end

node_genesys["Genesys Cloud"]

node_cli -->|"invokes services"| node_composition
node_profiles -.->|"configures profiles"| node_composition
node_mcp -->|"registers tool"| node_flowtools
node_flowtools -->|"requests flow list"| node_composition
node_mcp -.->|"serves plans"| node_application
node_application -->|"plans operations"| node_composition
node_composition -.->|"tracks runs"| node_runstate
node_composition -.->|"reads profiles"| node_profile_store
node_composition -->|"runs capture"| node_capture
node_capture -.->|"fetches source"| node_provider
node_provider -->|"resolves resources"| node_readers
node_readers -->|"requests resource data"| node_platform
node_provider -->|"uses API client"| node_platform
node_platform -->|"sends GET requests"| node_genesys
node_capture -->|"walks dependencies"| node_resourcegraph
node_capture -->|"writes bundle"| node_bundle
node_bundle -->|"provides capture"| node_document
node_document -.->|"normalizes flows"| node_normalization
node_normalization -->|"extracts nodes"| node_extractnodes
node_normalization -->|"extracts edges"| node_extractedges
node_document -.->|"analyzes flows"| node_analysis
node_document -.->|"builds evidence"| node_evidence
node_evidence -.->|"grounds narration"| node_narration
node_document -->|"writes documentation"| node_markdown
node_document -->|"optionally renders"| node_renderer
node_renderer -.->|"produces PDF"| node_pdf

click node_cli "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/apps/cli/src/bin.ts"
click node_profiles "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/apps/cli/src/commands/profile.ts"
click node_mcp "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/apps/mcp-server/src/server.ts"
click node_flowtools "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/apps/mcp-server/src/tools/flows-list.ts"
click node_application "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/application/src/plan.ts"
click node_composition "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/composition/src/archivist-port.ts"
click node_runstate "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/application/src/run-state-machine.ts"
click node_profile_store "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/storage/src/profile-store.ts"
click node_capture "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/capture/src/capture-run.ts"
click node_resourcegraph "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/capture/src/resource-graph.ts"
click node_bundle "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/capture/src/bundle-writer.ts"
click node_provider "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/genesys-source/src/platform-source-provider.ts"
click node_readers "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/genesys-source/src/resource-readers.ts"
click node_platform "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/genesys-platform/src/client.ts"
click node_normalization "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/normalization/src/normalize.ts"
click node_extractnodes "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/normalization/src/extract-nodes.ts"
click node_extractedges "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/normalization/src/extract-edges.ts"
click node_analysis "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/analysis/src/diff.ts"
click node_evidence "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/narrative/src/evidence-pack.ts"
click node_narration "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/narrative/src/narration-provider.ts"
click node_document "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/composition/src/document-bundle-to-disk.ts"
click node_markdown "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/composition/src/render-narrative.ts"
click node_renderer "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/rendering/src/playwright-renderer.ts"
click node_pdf "https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/rendering/src/renderer.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_profiles,node_mcp,node_flowtools toneBlue
class node_application,node_composition,node_runstate,node_profile_store toneAmber
class node_capture,node_resourcegraph,node_bundle,node_provider,node_readers,node_platform toneMint
class node_normalization,node_extractnodes,node_extractedges,node_analysis,node_evidence,node_narration toneRose
class node_document,node_markdown,node_renderer,node_pdf,node_genesys toneIndigo
```

## Components

### User interfaces

- [Archivist CLI](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/apps/cli/src/bin.ts): `apps/cli/src/bin.ts`
- [Profile commands](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/apps/cli/src/commands/profile.ts): `apps/cli/src/commands/profile.ts`
- [MCP server](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/apps/mcp-server/src/server.ts): `apps/mcp-server/src/server.ts`
- [Flow-list tool](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/apps/mcp-server/src/tools/flows-list.ts): `apps/mcp-server/src/tools/flows-list.ts`

### Application orchestration

- [Application planning](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/application/src/plan.ts): `packages/application/src/plan.ts`
- [Archivist service](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/composition/src/archivist-port.ts): `packages/composition/src/archivist-port.ts`
- [Run state](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/application/src/run-state-machine.ts): `packages/application/src/run-state-machine.ts`
- [Profile storage](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/storage/src/profile-store.ts): `packages/storage/src/profile-store.ts`

### Capture and platform

- [Capture runner](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/capture/src/capture-run.ts): `packages/capture/src/capture-run.ts`
- [Resource graph](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/capture/src/resource-graph.ts): `packages/capture/src/resource-graph.ts`
- [Sealed bundle](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/capture/src/bundle-writer.ts): `packages/capture/src/bundle-writer.ts`
- [Genesys source adapter](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/genesys-source/src/platform-source-provider.ts): `packages/genesys-source/src/platform-source-provider.ts`
- [Resource readers](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/genesys-source/src/resource-readers.ts): `packages/genesys-source/src/resource-readers.ts`
- [Read-only API client](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/genesys-platform/src/client.ts): `packages/genesys-platform/src/client.ts`

### Analysis and narration

- [Flow normalization](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/normalization/src/normalize.ts): `packages/normalization/src/normalize.ts`
- [Node extraction](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/normalization/src/extract-nodes.ts): `packages/normalization/src/extract-nodes.ts`
- [Edge extraction](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/normalization/src/extract-edges.ts): `packages/normalization/src/extract-edges.ts`
- [Flow analysis](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/analysis/src/diff.ts): `packages/analysis/src/diff.ts`
- [Evidence pack](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/narrative/src/evidence-pack.ts): `packages/narrative/src/evidence-pack.ts`
- [AI narration](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/narrative/src/narration-provider.ts): `packages/narrative/src/narration-provider.ts`

### Documentation outputs

- [Documentation pipeline](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/composition/src/document-bundle-to-disk.ts): `packages/composition/src/document-bundle-to-disk.ts`
- [Markdown and diagrams](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/composition/src/render-narrative.ts): `packages/composition/src/render-narrative.ts`
- [Diagram renderer](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/rendering/src/playwright-renderer.ts): `packages/rendering/src/playwright-renderer.ts`
- [PDF output](https://github.com/mahmouddattiaa/genesys-archivist/blob/main/packages/rendering/src/renderer.ts): `packages/rendering/src/renderer.ts`

### Other components

- **Genesys Cloud**

## Connections

- Archivist CLI → Archivist service: invokes services (evidence: `apps/cli/src/bin.ts`)
- Profile commands → Archivist service: configures profiles
- MCP server → Flow-list tool: registers tool (evidence: `apps/mcp-server/src/server.ts`)
- Flow-list tool → Archivist service: requests flow list (evidence: `apps/mcp-server/src/tools/flows-list.ts`)
- MCP server → Application planning: serves plans
- Application planning → Archivist service: plans operations (evidence: `packages/application/src/plan.ts`)
- Archivist service → Run state: tracks runs
- Archivist service → Profile storage: reads profiles
- Archivist service → Capture runner: runs capture (evidence: `packages/composition/src/archivist-port.ts`)
- Capture runner → Genesys source adapter: fetches source
- Genesys source adapter → Resource readers: resolves resources (evidence: `packages/genesys-source/src/platform-source-provider.ts`)
- Resource readers → Read-only API client: requests resource data (evidence: `packages/genesys-source/src/resource-readers.ts`)
- Genesys source adapter → Read-only API client: uses API client (evidence: `packages/genesys-source/src/platform-source-provider.ts`)
- Read-only API client → Genesys Cloud: sends GET requests (evidence: `README.md`)
- Capture runner → Resource graph: walks dependencies (evidence: `packages/capture/src/capture-run.ts`)
- Capture runner → Sealed bundle: writes bundle (evidence: `packages/capture/src/capture-run.ts`)
- Sealed bundle → Documentation pipeline: provides capture (evidence: `README.md`)
- Documentation pipeline → Flow normalization: normalizes flows
- Flow normalization → Node extraction: extracts nodes (evidence: `packages/normalization/src/normalize.ts`)
- Flow normalization → Edge extraction: extracts edges (evidence: `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 (evidence: `README.md`)
- Documentation pipeline → Diagram renderer: optionally renders (evidence: `README.md`)
- Diagram renderer → PDF output: produces PDF (evidence: `packages/rendering/src/playwright-renderer.ts`)
