@cxbuilder/flow-config 2.1.0 → 2.2.0

package/.jsii

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

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2025-12-02
+
+- Admins can control the variable type
+- Added role based user guides
+
+## [2.1.1] - 2025-10-08
+
+- Fixed `associate3pApp` prop reference in `associate3pApp()` method to properly read from props
+- Added Unit tests for FlowConfigStack to verify `associate3pApp` configuration behavior
+
 ## [2.1.0] - 2025-10-08
 
 - Added `associate3pApp` stack prop which allow you turn off the automatic Agent Workspace app association

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).