@cxbuilder/flow-config 2.1.1 → 2.2.1

package/README.md

@@ -1,319 +1,281 @@
-# @cxbuilder/flow-config
+# FlowConfig for Amazon Connect
 
 [![CI/CD Pipeline](https://github.com/cxbuilder/flow-config/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/cxbuilder/flow-config/actions/workflows/ci-cd.yml)
 [![npm version](https://badge.fury.io/js/@cxbuilder%2Fflow-config.svg)](https://badge.fury.io/js/@cxbuilder%2Fflow-config)
 [![PyPI version](https://badge.fury.io/py/cxbuilder-flow-config.svg)](https://badge.fury.io/py/cxbuilder-flow-config)
 [![View on Construct Hub](https://constructs.dev/badge?package=%40cxbuilder%2Fflow-config)](https://constructs.dev/packages/@cxbuilder/flow-config)
 
-AWS CDK constructs for Amazon Connect FlowConfig - a third-party app for configuring variables and prompts in Connect contact flows.
+**Empower your business users to manage Amazon Connect contact flow configurations without IT involvement.**
 
-## Links
+FlowConfig is a third-party app for Amazon Connect that lets business users update customer messages, queue settings, and routing variables in real-time—without touching contact flows or deploying code.
 
-- [Screenshots](./docs/screenshots/)
-- [Architecture](./docs/Architecture.md)
-- [DataModel](./docs/DataModel.md)
+![FlowConfig Admin View](./docs/screenshots/landing-admin.png)
 
-## Installation
+## The Problem
 
-```bash
-npm install @cxbuilder/flow-config
-```
+Your contact center needs to respond quickly to changing conditions:
 
-## Usage
+- 🚨 **Emergency closures** require immediate routing changes
+- 🗓️ **Seasonal hours** need frequent prompt updates
+- 🌍 **Multi-language support** means managing dozens of message variants
+- 🏢 **Multiple locations** each need custom greetings and settings
+- ⏱️ **Queue thresholds** must adapt to call volume fluctuations
 
-### Standard Deployment (Public)
+But every change requires:
+- Opening Amazon Connect contact flow designer
+- Finding and updating multiple text blocks
+- Testing changes
+- Deploying updates
+- Waiting for IT availability
 
-```typescript
-import { FlowConfigStack } from '@cxbuilder/flow-config';
-import * as cdk from 'aws-cdk-lib';
+**There has to be a better way.**
 
-const app = new cdk.App();
-new FlowConfigStack(app, 'FlowConfigStack', {
-  prefix: 'my-flow-config',
-  env: {
-    region: 'us-east-1',
-    account: 'YOUR_ACCOUNT_ID',
-  },
-  cognito: {
-    domain: 'https://your-auth-domain.com',
-    userPoolId: 'us-east-1_YourPoolId',
-  },
-  connectInstanceArn:
-    'arn:aws:connect:us-east-1:YOUR_ACCOUNT:instance/YOUR_INSTANCE_ID',
-  alertEmails: ['admin@yourcompany.com'],
-});
-```
+## The Solution
 
-### VPC Private Deployment
+FlowConfig separates **configuration** from **logic**. Your contact flow designers build reusable flows once, and business users manage the values that drive them.
 
-For enhanced security, you can deploy the application to run entirely within a VPC with private endpoints:
+### What You Can Configure
 
-```typescript
-import { FlowConfigStack, VpcConfig } from '@cxbuilder/flow-config';
-import * as cdk from 'aws-cdk-lib';
+**Variables** - Settings that control contact flow behavior:
+- Boolean flags: `closure`, `offerCallback`, `holidayMode`
+- Numbers: `maxWaitTime`, `queueDepth`, `transferTimeout`
+- Text values: `skillLevel`, `routingMode`, `priority`
 
-const app = new cdk.App();
+**Prompts** - Customer-facing messages:
+- Multi-language support (English, Spanish, French, etc.)
+- Separate voice and chat content
+- Text-to-speech preview before going live
 
-// Configure VPC using string IDs - the stack will resolve these to CDK objects
-const vpcConfig: VpcConfig = {
-  vpcId: 'vpc-12345678',
-  lambdaSecurityGroupIds: ['sg-lambda123'],
-  privateSubnetIds: ['subnet-12345', 'subnet-67890'],
-  vpcEndpointSecurityGroupIds: ['sg-endpoint123'],
-};
+### Who Uses FlowConfig
 
-new FlowConfigStack(app, 'FlowConfigStack', {
-  prefix: 'my-flow-config',
-  env: {
-    region: 'us-east-1',
-    account: 'YOUR_ACCOUNT_ID',
-  },
-  cognito: {
-    domain: 'https://your-auth-domain.com',
-    userPoolId: 'us-east-1_YourPoolId',
-  },
-  connectInstanceArn:
-    'arn:aws:connect:us-east-1:YOUR_ACCOUNT:instance/YOUR_INSTANCE_ID',
-  alertEmails: ['admin@yourcompany.com'],
-  vpc: vpcConfig, // Enable VPC private deployment
-});
-```
+**👔 Edit Users**
+- Update all variables and prompts across all flow configurations
+- Change settings during high-volume events or emergencies
+- Update prompts for holidays, closures, and special events
+- Preview voice messages before customers hear them
+- Make changes instantly without IT involvement
 
-### Multi-Region Global Table Deployment
+**🔧 Administrators (Admin Access)**
+- Create and organize flow configurations
+- Define variable schema types (Text, Number, Boolean, Select)
+- Add/remove variables and prompts
+- Set up multi-language prompts for global operations
+- Import/export configurations across environments
+- Configure application settings (available locales and voices)
 
-For global resilience, deploy the application across multiple regions with DynamoDB Global Tables:
+**👀 Read-Only Users**
+- View all configurations and settings
+- Monitor what messages customers are currently hearing
+- Review variable values without editing capability
 
-#### Primary Region Setup
+## Quick Links
 
-```typescript
-import { FlowConfigStack, GlobalTableConfig } from '@cxbuilder/flow-config';
-import * as cdk from 'aws-cdk-lib';
+### 📘 I'm a Business User
+- [Edit User Guide](./docs/UserGuide-Edit.md) - Learn how to update variables and prompts
+- [Administrator Guide](./docs/UserGuide-Admin.md) - Create and manage configurations
+- [Read-Only User Guide](./docs/UserGuide-Read.md) - View configurations
 
-const app = new cdk.App();
+### 🛠️ I'm a Developer/Architect
+- [Installation & Deployment](./docs/Installation.md) - Get started deploying FlowConfig
+- [Architecture](./docs/Architecture.md) - Understand the technical design
+- [Data Model](./docs/DataModel.md) - Explore the data structure
 
-// Primary region creates the global table with replicas
-const primaryGlobalTable: GlobalTableConfig = {
-  isPrimaryRegion: true,
-  replicaRegions: ['us-west-2', 'eu-west-1'],
-};
+### 🎯 I'm Evaluating This Solution
+- [Screenshots](./docs/screenshots/) - See the interface in action
+- [Use Cases](#common-use-cases) - Real-world scenarios below
+- [Features](#key-features) - What's included
 
-new FlowConfigStack(app, 'FlowConfigStack-Primary', {
-  prefix: 'my-flow-config',
-  env: {
-    region: 'us-east-1',
-    account: 'YOUR_ACCOUNT_ID',
-  },
-  cognito: {
-    domain: 'https://your-auth-domain.com',
-    userPoolId: 'us-east-1_YourPoolId',
-  },
-  connectInstanceArn:
-    'arn:aws:connect:us-east-1:YOUR_ACCOUNT:instance/YOUR_INSTANCE_ID',
-  alertEmails: ['admin@yourcompany.com'],
-  globalTable: primaryGlobalTable, // Enable global table
-});
-```
+## Common Use Cases
 
-#### Secondary Region Setup
+### 🏢 Multi-Branch Operations
 
-```typescript
-new FlowConfigStack(app, 'FlowConfigStack-Secondary', {
-  prefix: 'my-flow-config',
-  env: {
-    region: 'us-west-2',
-    account: 'YOUR_ACCOUNT_ID',
-  },
-  cognito: {
-    domain: 'https://your-auth-domain.com',
-    userPoolId: 'us-west-2_YourPoolId',
-  },
-  connectInstanceArn:
-    'arn:aws:connect:us-west-2:YOUR_ACCOUNT:instance/YOUR_INSTANCE_ID',
-  alertEmails: ['admin@yourcompany.com'],
-  globalTable: {
-    isPrimaryRegion: false, // Reference global table
-  },
-});
-```
+**Challenge**: 50 branch offices, each with unique phone numbers and custom greetings, but sharing the same contact flow logic.
 
-## Features
+**Solution**: Create one flow configuration per branch (e.g., `branch-office-austin`, `branch-office-seattle`). Each branch gets custom prompts and settings while using a single, centralized contact flow design.
 
-- **Serverless Architecture**: Built with AWS Lambda, DynamoDB, and API Gateway
-- **Amazon Connect Integration**: GetConfig Lambda function integrated directly with Connect contact flows
-- **Third-Party App**: Web-based interface embedded in Amazon Connect Agent Workspace
-- **Multi-Language Support**: Configure prompts for different languages and channels (voice/chat)
-- **Real-time Preview**: Text-to-speech preview using Amazon Polly
-- **Secure Access**: Integration with Amazon Connect and AWS Verified Permissions
-- **Flexible Deployment Options**:
-  - **Single-Region**: Standard deployment with regional DynamoDB table
-  - **Multi-Region**: Global table support with automatic replication across regions
-  - **Public Deployment**: Standard internet-accessible API Gateway and Lambda functions
-  - **VPC Private Deployment**: Private API Gateway endpoints, VPC-enabled Lambda functions, and VPC endpoints for enhanced security
+**Result**: Onboard new branches in minutes. Local staff can update their own greetings and settings without IT involvement.
 
-## GetConfig Lambda Integration
+---
 
-The GetConfig Lambda function is used within contact flows to access your flow configs. This function is automatically integrated with your Amazon Connect instance during deployment.
+### 🚨 Emergency Response
 
-### Contact Flow Event Structure
+**Challenge**: Fire alarm requires immediate call center closure. Every minute of delay means confused customers and wasted agent time.
 
-The Lambda function handles Amazon Connect Contact Flow events with the following structure:
+**Solution**: Business users open FlowConfig, toggle `closure: true`, and save. All new calls immediately hear the closure message and are routed appropriately.
 
-```json
-{
-  "Details": {
-    "Parameters": {
-      "id": "main-queue",
-      "lang": "es-US"
-    },
-    "ContactData": {
-      "Channel": "VOICE",
-      "LanguageCode": "en-US"
-    }
-  }
-}
-```
+**Result**: Response time measured in seconds, not hours. No contact flow changes, no deployments, no IT tickets.
 
-### Input Parameters and Priority
+---
 
-1. **Required Parameters**:
+### 🌍 Global Customer Support
 
-   - **`id`**: Flow configuration identifier (always required)
-     - Provided via `Details.Parameters.id`
+**Challenge**: Supporting customers in English, Spanish, and French requires managing hundreds of prompt variants across dozens of contact flows.
 
-2. **Optional Language Selection** (in order of precedence):
+**Solution**: Define prompts once in FlowConfig with all language variants. Contact flows automatically select the correct language based on customer preference.
 
-   - `Details.Parameters.lang` (highest priority)
-   - `Details.ContactData.LanguageCode`
-   - Defaults to `"en-US"`
+**Result**: Add a new language by updating prompts in FlowConfig—no contact flow changes required.
 
-3. **Channel Detection**:
-   - Automatically read from `Details.ContactData.Channel`
-   - Supports `"VOICE"` and `"CHAT"`
-   - Defaults to `"voice"`
+---
 
-### Alternative Input Format (Testing)
+### 📊 Dynamic Queue Management
 
-For direct testing or non-Connect invocation:
+**Challenge**: Call volume spikes require rapid adjustment of queue thresholds, wait times, and callback offerings.
 
-```json
-{
-  "id": "main-queue",
-  "lang": "es-US",
-  "channel": "voice"
-}
-```
+**Solution**: Business users adjust variables like `maxQueueDepth`, `maxWaitTime`, and `offerCallback` in real-time based on current conditions.
 
-### Function Behavior
+**Result**: Contact center supervisors respond to changing conditions without waiting for IT or risking contact flow mistakes.
 
-1. **Parameter Resolution**:
+---
 
-   - Extracts `id` from Connect event parameters (required)
-   - Resolves language from parameters → attributes → default
-   - Determines channel from Contact Flow event data
+## Key Features
 
-2. **Processing Steps**:
+**For Business Users:**
+- ✅ **No-Code Interface** - Simple web UI embedded in Amazon Connect Agent Workspace
+- 🎧 **Preview Before Publishing** - Hear exactly how prompts will sound using Amazon Polly text-to-speech
+- 🌍 **Multi-Language Support** - Manage prompts in multiple languages with separate voice and chat content
+- ⚡ **Instant Updates** - Changes take effect immediately for new customer contacts
+- 🔒 **Role-Based Access** - Three access levels: Admin, Edit, and Read-Only
 
-   - Retrieves the flow config from DynamoDB using the provided ID
-   - Includes all variables from the flow config in the result
-   - For each prompt in the flow config:
-     - Selects the appropriate language version
-     - Uses voice content by default
-     - For chat channel:
-       - Uses chat-specific content if available
-       - Strips SSML tags from voice content if no chat content exists
+**For IT Teams:**
+- 🏗️ **Serverless Architecture** - Built on AWS Lambda, DynamoDB, and API Gateway
+- 🔌 **Native Connect Integration** - Seamlessly integrates with contact flows via Lambda function
+- 🔐 **Secure by Design** - AWS Cognito authentication with role-based access control
+- 📦 **Easy Deployment** - Single CDK construct deploys the entire stack
+- 🌐 **Flexible Architecture** - Supports single-region, multi-region, public, or VPC-private deployments
+- 📤 **Import/Export** - Move configurations between environments (dev/test/prod)
 
-3. **Output**:
-   - Returns a flattened object containing:
-     - All variable key-value pairs from the flow config
-     - All prompt values resolved for the specified language and channel
+---
 
-### Setting Up in Contact Flow
+## Getting Started
 
-1. **Add "Invoke AWS Lambda function" block** to your contact flow
-2. **Select the GetConfig Lambda function** (deployed as `${prefix}`)
-3. **Configure parameters**:
+### For Developers
 
-```json
-{
-  "id": "main-queue"
-}
+**Installation:**
+
+```bash
+npm install @cxbuilder/flow-config
+```
+
+**Basic Usage:**
+
+```typescript
+import { FlowConfigStack } from '@cxbuilder/flow-config';
+import * as cdk from 'aws-cdk-lib';
+
+const app = new cdk.App();
+new FlowConfigStack(app, 'FlowConfigStack', {
+  prefix: 'my-flow-config',
+  env: { region: 'us-east-1', account: 'YOUR_ACCOUNT_ID' },
+  cognito: {
+    domain: 'https://your-auth-domain.com',
+    userPoolId: 'us-east-1_YourPoolId',
+  },
+  connectInstanceArn: 'arn:aws:connect:us-east-1:YOUR_ACCOUNT:instance/YOUR_INSTANCE_ID',
+  alertEmails: ['admin@yourcompany.com'],
+});
 ```
 
-Or with explicit language:
+**Next Steps:**
+- See the [Installation Guide](./docs/Installation.md) for detailed deployment instructions
+- Review the [Architecture](./docs/Architecture.md) to understand the technical design
+- Explore advanced configurations (VPC private, multi-region, etc.)
+
+### For Contact Flow Designers
+
+**Using FlowConfig in Your Contact Flows:**
+
+1. Add an "Invoke AWS Lambda function" block
+2. Select the GetConfig Lambda function (automatically deployed)
+3. Pass the configuration ID as a parameter:
 
 ```json
 {
-  "id": "main-queue",
-  "lang": "es-US"
+  "id": "main-queue"
 }
 ```
 
-### Using Returned Data
-
-The Lambda response is automatically available in subsequent blocks:
+4. Use the returned values in subsequent blocks:
+   - Variables: `$.External.closure`, `$.External.maxWaitTime`
+   - Prompts: `$.External.welcome`, `$.External.holdMessage`
 
-- **Set contact attributes**: Use `$.External.variableName`
-- **Play prompt**: Use `$.External.promptName`
-- **Check contact attributes**: Reference returned variables for routing decisions
-
-### Example Contact Flow Integration
+**Example Flow:**
 
 ```
-[Get customer input] → [Invoke Lambda: GetConfig]
-                           ↓
-                      [Set contact attributes]
-                           ↓
-                      [Play prompt: $.External.welcomeMessage]
-                           ↓
-                      [Route based on: $.External.routingMode]
+[Entry Point] → [Invoke Lambda: GetConfig with id="main-queue"]
+                      ↓
+                [Check: $.External.closure = true?]
+                      ↓                    ↓
+                  [Yes: Play           [No: Continue
+                   $.External.          to queue]
+                   closureMessage]
 ```
 
-### Size Considerations
+For detailed Lambda integration instructions, see the [Technical Reference](#technical-reference) below.
 
-- Amazon Connect has a Lambda response size limit of 32KB
-- The combined size of returned variables and prompts should be less than this limit
-- For large flow configs with many prompts or languages, consider implementing pagination or selective loading
+---
 
-### Logger
+## Technical Reference
 
-[Lambda PowerTools Logger](https://docs.powertools.aws.dev/lambda/typescript/latest/core/logger/) provides a lightweight logger implementation with JSON output.
+### GetConfig Lambda Integration
 
-Tips:
+The GetConfig Lambda function is used within contact flows to access your flow configs. This function is automatically integrated with your Amazon Connect instance during deployment.
 
-- Use the `appendKeys()` method to add `ContactId` to your connect log lambda output.
+**Lambda Parameters:**
 
-### Open API Spec
+- **Required**: `id` - The flow configuration identifier
+- **Optional**: `lang` - Language code (defaults to contact's language or `en-US`)
+- **Auto-detected**: `channel` - Voice or chat (detected from contact data)
 
-This template defines an Open API Spec for the API GW Lambdas. This allows use to generate a TypeScript api client to be used by the frontend app. We can also generate a API client in any language from the same spec to allow the client to better integrate with our apps.
+**Lambda Response:**
 
-- [constructs/aws-openapigateway-lambda](https://docs.aws.amazon.com/solutions/latest/constructs/aws-openapigateway-lambda.html)
-- [OpenAPI Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi)
-- [OpenApy TypeScript Generator](https://openapi-ts.pages.dev/introduction)
+Returns a flattened object containing all variables and prompts from the configuration:
 
-## Development
+```json
+{
+  "closure": "false",
+  "maxWaitTime": "600",
+  "offerCallback": "true",
+  "welcome": "Thank you for calling...",
+  "holdMessage": "Please continue to hold..."
+}
+```
 
-### Frontend Development
+**Key Behaviors:**
 
-The frontend React application integrates with Amazon Connect Agent Workspace using the Connect SDK:
+- Automatically selects the correct language variant based on customer preference
+- Returns chat-specific content for chat contacts (or strips SSML from voice content)
+- Includes all variables as key-value pairs
+- 32KB response size limit (Amazon Connect restriction)
 
-```bash
-# Start local development server
-npm start
+**Detailed Documentation:**
 
-# Build for production
-npm run build
-```
+For complete API documentation, event structures, and advanced usage, see:
+- [Architecture Documentation](./docs/Architecture.md) - Full Lambda integration details
+- [Data Model](./docs/DataModel.md) - Configuration structure and schemas
 
-For local development, point your Amazon Connect third-party app configuration to `localhost:3000`. The application requires execution within Agent Workspace for Connect SDK functionality.
+---
 
-### Lambda Development
+## Development
 
-Lambda functions are bundled automatically during the build process:
+For developers contributing to FlowConfig or customizing the deployment:
+
+**Frontend Development:**
 
 ```bash
-# Bundle Lambda functions
-npm run build:lambdas
+npm start              # Local dev server
+npm run build          # Production build
+```
+
+**Lambda Development:**
 
-# Full build (CDK + Frontend + Lambdas)
-npm run build
+```bash
+npm run build:lambdas  # Bundle Lambda functions
+npm run build          # Full build (CDK + Frontend + Lambdas)
 ```
+
+**Additional Resources:**
+- Uses [Lambda PowerTools](https://docs.powertools.aws.dev/lambda/typescript/latest/) for logging
+- OpenAPI spec for API Gateway enables client generation in any language
+- Frontend built with React and Amazon CloudScape Design System
+
+For detailed development setup, see [Installation Guide](./docs/Installation.md).