# service-cloud-voice/servicecloudvoicelambdas architecture

> Architecture diagram of the GitHub repository service-cloud-voice/servicecloudvoicelambdas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/service-cloud-voice/servicecloudvoicelambdas
- Repository: https://github.com/service-cloud-voice/servicecloudvoicelambdas

## Overview

#### Purpose and deployment surface
ServiceCloudVoiceLambdas is an AWS serverless integration package for Salesforce Service Cloud Voice contact centers running on Amazon Connect. Its deployable entry surface is the Serverless Application Repository/SAM application at `ServerlessApplication/ServiceCloudVoiceLambdas.yaml`; supporting CloudFormation stacks provision Connect configuration, secrets, events, voicemail, realtime alerts, and bring-your-own-account/tenant variants under `cloudformation/`.

#### Contact-flow API adapters
Amazon Connect contact flows invoke Node.js Lambda handlers that bridge call lifecycle actions to Salesforce-facing APIs:
- Salesforce REST operations and phone-call flow handling: `invokeSfRestApi/handler.js`, `invokeSfRestApi/sfRestApi.js`, `invokeSfRestApi/SFSPhoneCallFlow.js`.
- Telephony Integration API operations: `invokeTelephonyIntegrationApi/handler.js`, `invokeTelephonyIntegrationApi/telephonyIntegrationApi.js`.
- Voice Feature Service integration: `invokeVfsIntegrationApi/handler.js`, `invokeVfsIntegrationApi/vfsIntegrationApi.js`.

These functions form the primary synchronous boundary between Connect flow attributes/events and external Salesforce services. Their `config`, secret, Axios-wrapper, and logging modules keep credentials, request transport, and operational behavior separated from handlers.

#### Call-event and record synchronization
Asynchronous call data is propagated to Salesforce through dedicated event handlers:
- Contact event handling: `handleContactEvents/handler.js`, `handleContactEvents/utils.js`.
- Contact Trace Record synchronization: `ctrDataSync/handler.js`, `ctrDataSync/utils.js`.
- Contact-data/transcript upload status and transfer: `contactDataSync/handler.js`, `contactDataSync/transcriptUploader.js`, `contactDataSync/sfRestApi.js`.

The control boundary is AWS-generated Connect/contact data on one side and Salesforce REST APIs on the other, with each Lambda owning event parsing and outbound synchronization.

#### Real-time and post-call analytics pipeline
The repository supports live and post-call conversational analytics:
- Kinesis Video Streams consumption trigger: `kvsConsumerTrigger/kvs_trigger.js`.
- Java streaming transcription service: `kvsTranscriber/src/main/java/com/amazonaws/kvstranscribestreaming/KVSTranscribeStreamingService.java`, `kvsTranscriber/src/main/java/com/amazonaws/kvstranscribestreaming/TranscribedSegmentWriter.java`.
- Contact Lens processing and consumer stages: `contactLensProcessor/handler.js`, `contactLensConsumer/handler.js`.
- Post-call analysis trigger: `postCallAnalysisTrigger/handler.js`, `postCallAnalysisTrigger/telephonyIntegrationApi.js`.
- Real-time alert processing: `realtimeAlert/handler.js`.

The likely staged flow is KVS audio → Amazon Transcribe streaming → persisted/transmitted transcript segments → Contact Lens or post-call signals → Salesforce telephony integration updates and alerts.

#### Voicemail processing pipeline
Voicemail is modeled as independent processing stages: `voiceMailAudioProcessing/handler.js`, `voiceMailTranscribe/handler.js`, and `voiceMailPackaging/handler.js`. These separate audio transformation, transcription, and final voicemail payload packaging. Voicemail infrastructure is defined centrally in `cloudformation/VoiceMailStack.yaml`.

#### Multi-organization variants
Dedicated multi-org Lambdas add tenant-aware routing/caching around the same contact-event, Contact Lens, post-call, and voicemail workflows: `multiorgHandleContactEvents/handler.js`, `multiorgContactLensConsumer/handler.js`, `multiorgPostCallAnalysisTrigger/handler.js`, and `multiorgVoiceMailPackaging/handler.js`. Provisioning and configuration support reside in `cloudformation/MultiOrgConnectConfigurationStack.yaml` and `cloudformation/MultiorgProvisioningServiceStack.yaml`.

#### Security, operations, and runtime boundaries
Node.js Lambda functions use reusable per-function dependency layers under `layers/`, while transcription is a Gradle/Java service under `kvsTranscriber/`. Secrets and authorization-key management are explicitly isolated in `authKeysSSMUtil/index.js`, `authKeysSSMUtil/secretUtils.js`, and `cloudformation/SecretManagerStack.yaml`, indicating AWS Systems Manager Parameter Store/Secrets Manager integration. A separate Python health-check application validates deployed resources and reports findings via `healthCheck/healthcheck.py`, `healthCheck/validators/all_validators.py`, and `cloudformation/BYOAHealthCheckStack.yaml`.

Main entry points: [`multiorgHandleContactEvents/handler.js`](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/multiorgHandleContactEvents/handler.js) (Tenant-aware workflows), [`invokeSfRestApi/handler.js`](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/invokeSfRestApi/handler.js) (Contact-flow REST adapter), [`contactLensConsumer/handler.js`](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/contactLensConsumer/handler.js) (Contact Lens consumer), [`ServerlessApplication/ServiceCloudVoiceLambdas.yaml`](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/ServerlessApplication/ServiceCloudVoiceLambdas.yaml) (SAM application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment & Security"]
  node_sam["SAM application<br/>deployment entrypoint"]
  node_secrets[("Secrets &amp; auth keys<br/>credential management<br/>[index.js]")]
  node_health["BYOA health checks<br/>Python validator<br/>[healthcheck.py]"]
end

subgraph group_contact["Connect to Salesforce"]
  node_connect{{"Amazon Connect<br/>contact center runtime"}}
  node_sf{{"Salesforce services<br/>external API boundary"}}
  node_flow_api["Contact-flow REST adapter<br/>Node.js Lambda<br/>[handler.js]"]
  node_telephony_api["Telephony API adapter<br/>Node.js Lambda<br/>[handler.js]"]
  node_vfs_api["Voice Feature adapter<br/>Node.js Lambda<br/>[handler.js]"]
  node_contact_events["Contact event sync<br/>event Lambda<br/>[handler.js]"]
  node_ctr_sync["CTR data sync<br/>event Lambda<br/>[handler.js]"]
  node_contact_data["Contact data &amp; transcript sync<br/>event Lambda<br/>[handler.js]"]
end

subgraph group_analytics["Analytics &amp; Alerts"]
  node_kvs_trigger["KVS consumer trigger<br/>stream trigger<br/>[kvs_trigger.js]"]
  node_transcriber["Streaming transcriber<br/>Java service"]
  node_lens_processor["Contact Lens processor<br/>processing Lambda<br/>[handler.js]"]
  node_lens_consumer["Contact Lens consumer<br/>consumer Lambda<br/>[handler.js]"]
  node_post_call["Post-call analysis<br/>trigger Lambda<br/>[handler.js]"]
  node_alerts["Realtime alerts<br/>alert Lambda<br/>[handler.js]"]
end

subgraph group_voicemail["Voicemail"]
  node_vm_audio["Voicemail audio processing<br/>processing Lambda<br/>[handler.js]"]
  node_vm_transcribe["Voicemail transcription<br/>transcription Lambda<br/>[handler.js]"]
  node_vm_package["Voicemail packaging<br/>packaging Lambda<br/>[handler.js]"]
end

subgraph group_multiorg["Multi-org Variants"]
  node_multiorg["Tenant-aware workflows<br/>multi-org Lambda variants<br/>[handler.js]"]
end

node_sam -->|"provisions integration"| node_connect
node_sam -->|"deploys"| node_secrets
node_sam -->|"deploys"| node_flow_api
node_connect -->|"contact-flow invoke"| node_flow_api
node_connect -->|"contact-flow invoke"| node_telephony_api
node_connect -->|"contact-flow invoke"| node_vfs_api
node_flow_api -.->|"loads credentials"| node_secrets
node_telephony_api -.->|"loads credentials"| node_secrets
node_flow_api -->|"REST operations"| node_sf
node_telephony_api -->|"telephony operations"| node_sf
node_vfs_api -->|"voice features"| node_sf
node_connect -->|"contact events"| node_contact_events
node_connect -->|"trace records"| node_ctr_sync
node_contact_events -->|"synchronize"| node_sf
node_ctr_sync -->|"synchronize"| node_sf
node_contact_data -->|"upload status and transcripts"| node_sf
node_connect -->|"KVS audio"| node_kvs_trigger
node_kvs_trigger -->|"stream audio"| node_transcriber
node_transcriber -->|"transcript segments"| node_contact_data
node_transcriber -->|"transcript signals"| node_lens_processor
node_lens_processor -->|"Contact Lens output"| node_lens_consumer
node_lens_consumer -->|"post-call signals"| node_post_call
node_post_call -->|"telephony updates"| node_sf
node_lens_consumer -->|"realtime signals"| node_alerts
node_connect -->|"voicemail audio"| node_vm_audio
node_vm_audio -->|"processed audio"| node_vm_transcribe
node_vm_transcribe -->|"transcript"| node_vm_package
node_vm_package -->|"voicemail payload"| node_sf
node_multiorg -.->|"tenant-aware variant"| node_contact_events
node_multiorg -.->|"tenant-aware variant"| node_lens_consumer
node_multiorg -.->|"tenant-aware variant"| node_post_call
node_multiorg -.->|"tenant-aware variant"| node_vm_package
node_health -.->|"validates resources"| node_connect

click node_sam "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/ServerlessApplication/ServiceCloudVoiceLambdas.yaml"
click node_secrets "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/authKeysSSMUtil/index.js"
click node_flow_api "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/invokeSfRestApi/handler.js"
click node_telephony_api "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/invokeTelephonyIntegrationApi/handler.js"
click node_vfs_api "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/invokeVfsIntegrationApi/handler.js"
click node_contact_events "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/handleContactEvents/handler.js"
click node_ctr_sync "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/ctrDataSync/handler.js"
click node_contact_data "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/contactDataSync/handler.js"
click node_kvs_trigger "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/kvsConsumerTrigger/kvs_trigger.js"
click node_transcriber "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/kvsTranscriber/src/main/java/com/amazonaws/kvstranscribestreaming/KVSTranscribeStreamingService.java"
click node_lens_processor "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/contactLensProcessor/handler.js"
click node_lens_consumer "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/contactLensConsumer/handler.js"
click node_post_call "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/postCallAnalysisTrigger/handler.js"
click node_alerts "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/realtimeAlert/handler.js"
click node_vm_audio "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/voiceMailAudioProcessing/handler.js"
click node_vm_transcribe "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/voiceMailTranscribe/handler.js"
click node_vm_package "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/voiceMailPackaging/handler.js"
click node_multiorg "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/multiorgHandleContactEvents/handler.js"
click node_health "https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/healthCheck/healthcheck.py"

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_sam,node_secrets,node_health toneBlue
class node_connect,node_sf,node_flow_api,node_telephony_api,node_vfs_api,node_contact_events,node_ctr_sync,node_contact_data toneAmber
class node_kvs_trigger,node_transcriber,node_lens_processor,node_lens_consumer,node_post_call,node_alerts toneMint
class node_vm_audio,node_vm_transcribe,node_vm_package toneRose
class node_multiorg toneIndigo
```

## Components

### Deployment & Security

- [SAM application](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/ServerlessApplication/ServiceCloudVoiceLambdas.yaml): deployment entrypoint · Deploys the serverless integration package. · `ServerlessApplication/ServiceCloudVoiceLambdas.yaml`
- [Secrets & auth keys](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/authKeysSSMUtil/index.js): credential management · Isolates authorization keys and secret access. · `authKeysSSMUtil/index.js`
- [BYOA health checks](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/healthCheck/healthcheck.py): Python validator · Validates deployed bring-your-own-account resources. · `healthCheck/healthcheck.py`

### Connect to Salesforce

- **Amazon Connect**: contact center runtime
- **Salesforce services**: external API boundary · Service Cloud Voice REST and telephony endpoints.
- [Contact-flow REST adapter](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/invokeSfRestApi/handler.js): Node.js Lambda · `invokeSfRestApi/handler.js`
- [Telephony API adapter](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/invokeTelephonyIntegrationApi/handler.js): Node.js Lambda · `invokeTelephonyIntegrationApi/handler.js`
- [Voice Feature adapter](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/invokeVfsIntegrationApi/handler.js): Node.js Lambda · `invokeVfsIntegrationApi/handler.js`
- [Contact event sync](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/handleContactEvents/handler.js): event Lambda · `handleContactEvents/handler.js`
- [CTR data sync](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/ctrDataSync/handler.js): event Lambda · `ctrDataSync/handler.js`
- [Contact data & transcript sync](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/contactDataSync/handler.js): event Lambda · `contactDataSync/handler.js`

### Analytics & Alerts

- [KVS consumer trigger](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/kvsConsumerTrigger/kvs_trigger.js): stream trigger · `kvsConsumerTrigger/kvs_trigger.js`
- [Streaming transcriber](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/kvsTranscriber/src/main/java/com/amazonaws/kvstranscribestreaming/KVSTranscribeStreamingService.java): Java service · Streams audio transcription and writes transcript segments. · `kvsTranscriber/src/main/java/com/amazonaws/kvstranscribestreaming/KVSTranscribeStreamingService.java`
- [Contact Lens processor](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/contactLensProcessor/handler.js): processing Lambda · `contactLensProcessor/handler.js`
- [Contact Lens consumer](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/contactLensConsumer/handler.js): consumer Lambda · `contactLensConsumer/handler.js`
- [Post-call analysis](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/postCallAnalysisTrigger/handler.js): trigger Lambda · `postCallAnalysisTrigger/handler.js`
- [Realtime alerts](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/realtimeAlert/handler.js): alert Lambda · `realtimeAlert/handler.js`

### Voicemail

- [Voicemail audio processing](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/voiceMailAudioProcessing/handler.js): processing Lambda · `voiceMailAudioProcessing/handler.js`
- [Voicemail transcription](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/voiceMailTranscribe/handler.js): transcription Lambda · `voiceMailTranscribe/handler.js`
- [Voicemail packaging](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/voiceMailPackaging/handler.js): packaging Lambda · `voiceMailPackaging/handler.js`

### Multi-org Variants

- [Tenant-aware workflows](https://github.com/service-cloud-voice/servicecloudvoicelambdas/blob/master/multiorgHandleContactEvents/handler.js): multi-org Lambda variants · Tenant-aware event, analytics, post-call, and voicemail routing. · `multiorgHandleContactEvents/handler.js`

## Connections

- SAM application → Amazon Connect: provisions integration
- SAM application → Secrets & auth keys: deploys
- SAM application → Contact-flow REST adapter: deploys
- Amazon Connect → Contact-flow REST adapter: contact-flow invoke
- Amazon Connect → Telephony API adapter: contact-flow invoke
- Amazon Connect → Voice Feature adapter: contact-flow invoke
- Contact-flow REST adapter → Secrets & auth keys: loads credentials
- Telephony API adapter → Secrets & auth keys: loads credentials
- Contact-flow REST adapter → Salesforce services: REST operations
- Telephony API adapter → Salesforce services: telephony operations
- Voice Feature adapter → Salesforce services: voice features
- Amazon Connect → Contact event sync: contact events
- Amazon Connect → CTR data sync: trace records
- Contact event sync → Salesforce services: synchronize
- CTR data sync → Salesforce services: synchronize
- Contact data & transcript sync → Salesforce services: upload status and transcripts
- Amazon Connect → KVS consumer trigger: KVS audio
- KVS consumer trigger → Streaming transcriber: stream audio
- Streaming transcriber → Contact data & transcript sync: transcript segments
- Streaming transcriber → Contact Lens processor: transcript signals
- Contact Lens processor → Contact Lens consumer: Contact Lens output
- Contact Lens consumer → Post-call analysis: post-call signals
- Post-call analysis → Salesforce services: telephony updates
- Contact Lens consumer → Realtime alerts: realtime signals
- Amazon Connect → Voicemail audio processing: voicemail audio
- Voicemail audio processing → Voicemail transcription: processed audio
- Voicemail transcription → Voicemail packaging: transcript
- Voicemail packaging → Salesforce services: voicemail payload
- Tenant-aware workflows → Contact event sync: tenant-aware variant
- Tenant-aware workflows → Contact Lens consumer: tenant-aware variant
- Tenant-aware workflows → Post-call analysis: tenant-aware variant
- Tenant-aware workflows → Voicemail packaging: tenant-aware variant
- BYOA health checks → Amazon Connect: validates resources