# jay-teeyo/sdd-summary-mcp architecture

> Architecture diagram of the GitHub repository jay-teeyo/sdd-summary-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jay-teeyo/sdd-summary-mcp
- Repository: https://github.com/jay-teeyo/sdd-summary-mcp

## Overview

SDD Summary is an MCP-backed prompt-testing toolkit for Genesys Cloud Copilot/AI Studio summaries, used through Kiro or Cursor. The principal workflow is to authenticate, gather transcripts, define requirements and test cases, evaluate prompt versions, inspect reports, and iterate. The graph groups this workflow into MCP orchestration, Genesys integration, evaluation state, and reporting. Some subsystem connections are documented only at the product level; those are cited to the README rather than implying unobserved internal calls.

Main entry points: [`mcp-server/src/tools/handlers.ts`](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/tools/handlers.ts) (Workflow handlers), [`mcp-server/src/genesys/client.ts`](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/client.ts) (Genesys API client), [`mcp-server/src/reports/build.ts`](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/build.ts) (Report construction), [`mcp-server/src/index.ts`](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/index.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["MCP orchestration"]
  node_mcp["MCP server<br/>[index.ts]"]
  node_tool_catalog["Tool catalog<br/>[definitions.ts]"]
  node_tool_handlers["Workflow handlers<br/>[handlers.ts]"]
  node_guidance["Pipeline guidance<br/>[pipelineGuide.ts]"]
  node_host_support["Host support<br/>[host.ts]"]
end

subgraph group_genesys["Genesys integration"]
  node_oauth["OAuth and tokens<br/>[auth.ts]"]
  node_genesys_api["Genesys API client<br/>[client.ts]"]
  node_conversation_search["Conversation search<br/>[analytics.ts]"]
  node_transcripts["Transcript retrieval<br/>[transcripts.ts]"]
  node_summary_settings["Summary prompts<br/>[summaries.ts]"]
  node_copilot["Copilot integration<br/>[copilot.ts]"]
end

subgraph group_evaluation["Evaluation workflow"]
  node_configuration["Project configuration<br/>[config.ts]"]
  node_storage[("Workspace data<br/>[storage.ts]")]
  node_eval_workflow["Requirements, cases, evaluations<br/>[handlers.ts]"]
end

subgraph group_reporting["Reports and insights"]
  node_reports["Report construction<br/>[build.ts]"]
  node_report_model["Report model and metrics<br/>[model.ts]"]
  node_report_comparison["Findings and diffs<br/>[findings.ts]"]
  node_report_diff["Run comparison<br/>[diff.ts]"]
  node_report_render["HTML report rendering<br/>[render.ts]"]
  node_report_templates["Report views"]
end

node_user(("Engineer"))
node_editor["Kiro / Cursor"]
node_genesys_cloud["Genesys Cloud"]

node_user -->|"requests workflow"| node_editor
node_editor -->|"invokes tools"| node_mcp
node_mcp -->|"loads definitions"| node_tool_catalog
node_mcp -->|"dispatches tools"| node_tool_handlers
node_mcp -->|"provides guidance"| node_guidance
node_guidance -->|"uses host instructions"| node_host_support
node_tool_handlers -->|"authenticates"| node_oauth
node_tool_handlers -->|"fetches transcripts"| node_transcripts
node_tool_handlers -->|"previews summaries"| node_summary_settings
node_tool_handlers -->|"checks API scopes"| node_genesys_api
node_genesys_api -->|"gets access tokens"| node_oauth
node_genesys_api -->|"sends API requests"| node_genesys_cloud
node_conversation_search -->|"queries API"| node_genesys_api
node_transcripts -->|"retrieves transcript data"| node_genesys_api
node_summary_settings -->|"uses API"| node_genesys_api
node_copilot -->|"uses API"| node_genesys_api
node_tool_handlers -.->|"searches conversations"| node_conversation_search
node_tool_handlers -.->|"uses integration"| node_copilot
node_tool_handlers -->|"loads configuration"| node_configuration
node_tool_handlers -->|"reads and writes workflow data"| node_storage
node_tool_handlers -->|"runs authoring and evaluation"| node_eval_workflow
node_tool_handlers -->|"builds dashboards"| node_reports
node_reports -->|"reads saved runs"| node_storage
node_reports -->|"builds report data"| node_report_model
node_reports -->|"compares runs"| node_report_diff
node_reports -->|"collects findings"| node_report_comparison
node_report_render -->|"renders report data"| node_report_model
node_report_render -.->|"uses report views"| node_report_templates
node_user -->|"configures OAuth"| node_genesys_cloud
node_user -->|"authors and evaluates prompts"| node_eval_workflow
node_eval_workflow -.->|"persists evaluation state"| node_storage
node_user -->|"reviews dashboards"| node_reports

click node_mcp "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/index.ts"
click node_tool_catalog "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/tools/definitions.ts"
click node_tool_handlers "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/tools/handlers.ts"
click node_guidance "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/pipelineGuide.ts"
click node_host_support "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/host.ts"
click node_configuration "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/config.ts"
click node_oauth "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/auth.ts"
click node_genesys_api "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/client.ts"
click node_conversation_search "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/analytics.ts"
click node_transcripts "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/transcripts.ts"
click node_summary_settings "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/summaries.ts"
click node_copilot "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/copilot.ts"
click node_storage "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/storage.ts"
click node_eval_workflow "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/tools/handlers.ts"
click node_reports "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/build.ts"
click node_report_model "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/model.ts"
click node_report_comparison "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/findings.ts"
click node_report_diff "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/diff.ts"
click node_report_render "https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/render.ts"
click node_report_templates "https://github.com/jay-teeyo/sdd-summary-mcp/tree/main/mcp-server/src/reports/templates"

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_mcp,node_tool_catalog,node_tool_handlers,node_guidance,node_host_support toneBlue
class node_oauth,node_genesys_api,node_conversation_search,node_transcripts,node_summary_settings,node_copilot toneAmber
class node_configuration,node_storage,node_eval_workflow toneMint
class node_reports,node_report_model,node_report_comparison,node_report_diff,node_report_render,node_report_templates toneRose
class node_user,node_editor,node_genesys_cloud toneIndigo
```

## Components

### MCP orchestration

- [MCP server](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/index.ts): `mcp-server/src/index.ts`
- [Tool catalog](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/tools/definitions.ts): `mcp-server/src/tools/definitions.ts`
- [Workflow handlers](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/tools/handlers.ts): `mcp-server/src/tools/handlers.ts`
- [Pipeline guidance](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/pipelineGuide.ts): `mcp-server/src/pipelineGuide.ts`
- [Host support](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/host.ts): `mcp-server/src/host.ts`

### Genesys integration

- [OAuth and tokens](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/auth.ts): `mcp-server/src/genesys/auth.ts`
- [Genesys API client](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/client.ts): `mcp-server/src/genesys/client.ts`
- [Conversation search](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/analytics.ts): `mcp-server/src/genesys/analytics.ts`
- [Transcript retrieval](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/transcripts.ts): `mcp-server/src/genesys/transcripts.ts`
- [Summary prompts](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/summaries.ts): `mcp-server/src/genesys/summaries.ts`
- [Copilot integration](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/genesys/copilot.ts): `mcp-server/src/genesys/copilot.ts`

### Evaluation workflow

- [Project configuration](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/config.ts): `mcp-server/src/config.ts`
- [Workspace data](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/storage.ts): `mcp-server/src/storage.ts`
- [Requirements, cases, evaluations](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/tools/handlers.ts): `mcp-server/src/tools/handlers.ts`

### Reports and insights

- [Report construction](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/build.ts): `mcp-server/src/reports/build.ts`
- [Report model and metrics](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/model.ts): `mcp-server/src/reports/model.ts`
- [Findings and diffs](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/findings.ts): `mcp-server/src/reports/findings.ts`
- [Run comparison](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/diff.ts): `mcp-server/src/reports/diff.ts`
- [HTML report rendering](https://github.com/jay-teeyo/sdd-summary-mcp/blob/main/mcp-server/src/reports/render.ts): `mcp-server/src/reports/render.ts`
- [Report views](https://github.com/jay-teeyo/sdd-summary-mcp/tree/main/mcp-server/src/reports/templates): `mcp-server/src/reports/templates`

### Other components

- **Engineer**
- **Kiro / Cursor**
- **Genesys Cloud**

## Connections

- Engineer → Kiro / Cursor: requests workflow (evidence: `README.md`)
- Kiro / Cursor → MCP server: invokes tools (evidence: `README.md`)
- MCP server → Tool catalog: loads definitions (evidence: `mcp-server/src/index.ts`)
- MCP server → Workflow handlers: dispatches tools (evidence: `mcp-server/src/index.ts`)
- MCP server → Pipeline guidance: provides guidance (evidence: `mcp-server/src/index.ts`)
- Pipeline guidance → Host support: uses host instructions (evidence: `mcp-server/src/pipelineGuide.ts`)
- Workflow handlers → OAuth and tokens: authenticates (evidence: `mcp-server/src/tools/handlers.ts`)
- Workflow handlers → Transcript retrieval: fetches transcripts (evidence: `mcp-server/src/tools/handlers.ts`)
- Workflow handlers → Summary prompts: previews summaries (evidence: `mcp-server/src/tools/handlers.ts`)
- Workflow handlers → Genesys API client: checks API scopes (evidence: `mcp-server/src/tools/handlers.ts`)
- Genesys API client → OAuth and tokens: gets access tokens (evidence: `mcp-server/src/genesys/client.ts`)
- Genesys API client → Genesys Cloud: sends API requests (evidence: `mcp-server/src/genesys/client.ts`)
- Conversation search → Genesys API client: queries API (evidence: `mcp-server/src/genesys/analytics.ts`)
- Transcript retrieval → Genesys API client: retrieves transcript data (evidence: `mcp-server/src/genesys/transcripts.ts`)
- Summary prompts → Genesys API client: uses API (evidence: `mcp-server/src/genesys/summaries.ts`)
- Copilot integration → Genesys API client: uses API (evidence: `mcp-server/src/genesys/copilot.ts`)
- Workflow handlers → Conversation search: searches conversations (evidence: `mcp-server/src/tools/handlers.ts`)
- Workflow handlers → Copilot integration: uses integration (evidence: `mcp-server/src/tools/handlers.ts`)
- Workflow handlers → Project configuration: loads configuration (evidence: `mcp-server/src/tools/handlers.ts`)
- Workflow handlers → Workspace data: reads and writes workflow data (evidence: `mcp-server/src/tools/handlers.ts`)
- Workflow handlers → Requirements, cases, evaluations: runs authoring and evaluation (evidence: `README.md`)
- Workflow handlers → Report construction: builds dashboards (evidence: `mcp-server/src/tools/handlers.ts`)
- Report construction → Workspace data: reads saved runs (evidence: `mcp-server/src/reports/build.ts`)
- Report construction → Report model and metrics: builds report data (evidence: `mcp-server/src/reports/build.ts`)
- Report construction → Run comparison: compares runs (evidence: `mcp-server/src/reports/build.ts`)
- Report construction → Findings and diffs: collects findings (evidence: `mcp-server/src/reports/build.ts`)
- HTML report rendering → Report model and metrics: renders report data (evidence: `mcp-server/src/reports/render.ts`)
- HTML report rendering → Report views: uses report views
- Engineer → Genesys Cloud: configures OAuth (evidence: `README.md`)
- Engineer → Requirements, cases, evaluations: authors and evaluates prompts (evidence: `README.md`)
- Requirements, cases, evaluations → Workspace data: persists evaluation state (evidence: `mcp-server/src/tools/handlers.ts`)
- Engineer → Report construction: reviews dashboards (evidence: `README.md`)