# Architecture details
<a name="architecture-details"></a>

This section describes the components and AWS services that make up this solution and the architecture details on how these components work together.

## AWS services in this solution
<a name="aws-services-in-this-solution"></a>

The following AWS services are included in this solution:


| AWS service | Description | 
| --- | --- | 
|   [Amazon API Gateway](https://aws.amazon.com/api-gateway/)   |   **Core.** Used for internal API management.  | 
|   [AWS CloudFormation](https://aws.amazon.com/cloudformation/)   |   **Core.** Used to deploy the solution.  | 
|   [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/)   |   **Core.** Used for monitoring and logs.  | 
|   [Amazon Cognito](https://aws.amazon.com/cognito/)   |   **Core.** Used for user management.  | 
|   [AWS Identity and Access Management](https://aws.amazon.com/iam/)   |   **Core.** Used for user role and permissions management.  | 
|   [AWS Key Management Service](https://aws.amazon.com/kms/)   |   **Core.** Used for encryption.  | 
|   [AWS Lambda](https://aws.amazon.com/lambda/)   |   **Core.** Provides logic for chatbot interactions and provides extension capabilities for Amazon Translate before and after interaction with Amazon Lex.  | 
|   [Amazon Lex](https://aws.amazon.com/lex/)   |   **Core.** Provides the advanced deep learning functionalities of ASR for converting speech to text, and NLU to recognize the intent of the text.  | 
|   [Amazon OpenSearch Service](https://aws.amazon.com/elasticsearch-service/)   |   **Core.** Provides question bank, metrics, feedback indices, and provides OpenSearch Dashboards for chatbot usage.  | 
|   [Amazon SNS](https://aws.amazon.com/pm/sns/)   |   **Core.** Used for notifications, such as feedback.  | 
|   [Amazon Data Firehose](https://aws.amazon.com/kinesis/data-firehose)   |   **Supporting.** Delivers logs and metrics data to an Amazon S3 bucket.  | 
|   [Amazon Polly](https://aws.amazon.com/polly/)   |   **Supporting.** Used for Interactive Voice Response systems. It provides text to speech capabilities to relay the response back in the voice of choice.  | 
|   [Amazon S3](https://aws.amazon.com/s3/)   |   **Supporting.** Provides object storage for content designer UI data and logs and metrics data.  | 
|   [AWS Systems Manager Parameter Store](https://aws.amazon.com/systems-manager/features/#Parameter_Store)   |   **Supporting.** Provides secure, hierarchical storage for configuration data management and secrets management.  | 
|   [Amazon Translate](https://aws.amazon.com/translate/)   |   **Supporting.** Provides multi-language support to your customer’s bot interactions. You can maintain question and answer banks in a single language while still offering support to customers who interact with the bot in other languages through the use of Amazon Translate.  | 
|   [Amazon Bedrock](https://aws.amazon.com/bedrock/)   |   **Optional.** This solution utilizes Bedrock for embedding models, LLM models, knowledge base, and guardrails.  | 
|   [Amazon Connect](https://aws.amazon.com/connect/)   |   **Optional.** Provides an omnichannel cloud contact center. If you implement this component, you can create personalized experiences for your customers. For example, you can dynamically offer chat and voice contact, based on such factors as customer preference and estimated wait times. Agents, meanwhile, conveniently handle all customers from just one interface. For example, they can chat with customers, and create or respond to tasks as they are routed to them.  | 
|   [Amazon Kendra](https://aws.amazon.com/kendra/)   |   **Optional.** Hosts unstructured datasets hosted in an index. You can also use Amazon Kendra to provide semantic search capabilities to your question bank through the use of Amazon Kendra FAQs.  | 

## Amazon Lex web client
<a name="amazon-lex-web-client"></a>

Amazon Lex allows conversational interfaces to be integrated into applications such as the Amazon Lex web client. An Amazon Lex chatbot uses *intents* to encapsulate the purpose of an interaction, and *slots* to capture elements of information from the interaction. Since QnABot on AWS has a single purpose, to answer a user’s question, it defines just one intent. This intent has a single slot which is trained to capture the text of the question. QnABot on AWS also uses `AMAZON.FallBackIntent` to ensure that all user input is processed. To learn more about how Amazon Lex bots work, and to understand the concepts of intents, slots, sample values, fulfillment functions, see the [Amazon Lex Developer Guide](https://docs.aws.amazon.com/lex/latest/dg/what-is.html).

The QnABot on AWS Amazon Lex web client is deployed to an Amazon S3 bucket in your account, and accessed via Amazon API Gateway.

## Amazon Alexa devices
<a name="amazon-alexa-devices"></a>

Amazon Alexa devices interact with QnABot on AWS using an Alexa skill. Like an Amazon Lex chatbot, an Alexa skill also uses *intents* to encapsulate the purpose of an interaction, and *slots* to capture elements of information from the interaction.

The Alexa QnABot on AWS skill uses the same `Bot fulfillment` Lambda function as the Amazon Lex chatbot. When you ask a question, for example, ` "Alexa, ask Q and A, How can I include pictures in Q and A Bot answers?" `, your Alexa device interacts with the skill you created, which in turn invokes the `Bot fulfillment` Lambda function in your AWS account, passing the transcribed question as a parameter.

## Content designer UI
<a name="content-designer-ui"></a>

The QnABot on AWS content designer UI, like the Amazon Lex web client, is also deployed to an Amazon S3 bucket and accessed via Amazon API Gateway, and it too retrieves configuration from an API Gateway endpoint. The content designer UI requires the user to sign in with credentials defined in a Cognito user pool.

Using temporary AWS credentials from Cognito, the content designer UI interacts with secure API Gateway endpoints backed by the content designer Lambda functions. All interactions with Amazon OpenSearch Service and Amazon Lex are handled by these Lambda functions.

# How QnABot on AWS works
<a name="how-qnabot-on-aws-works"></a>

This solution is powered by the same technology as Alexa. The Amazon Lex component provides the tools that you need to tackle challenging deep learning problems, such as speech recognition and language understanding, through an easy-to-use fully managed service. Amazon Lex integrates with AWS Lambda, which you can use to initiate functions for running your backend business logic for data retrieval and updates. Once built, your bot can be deployed directly to chat platforms, mobile clients, and IoT devices. You can also use the reports provided to track metrics for your bot. This solution provides a scalable, secure, easy to use, end-to-end solution to build, publish, and monitor your bots.

Intelligent contact centers leverage conversational UX engines like Amazon Lex in order to provide proactive service to customers. Amazon Lex uses a deep learning engine that combines ASR and NLU to manage the customer experience. This enables it to be natural and adaptable to customer needs.

Chatbots are the starting point for many organizations. Amazon Lex comes with both voice and text. Amazon Lex has many application integrations for popular messaging platforms such as Slack and Facebook.

For Interactive Voice Response systems you can utilize the Text to speech capabilities of Amazon Polly to relay the response back in the voice of your choice.

To help fulfill many self-service requests, you can integrate Amazon Lex with your data or applications to retrieve information or use Amazon Kendra to search for the most accurate answers from your unstructured data sets.

The following figure illustrates a reference architecture for how QnABot on AWS integrates with external components.

 **Reference architecture for QnABot on AWS integrations with external components** 

![\[ref architecture integrations\]](http://docs.aws.amazon.com/solutions/latest/qnabot-on-aws/images/ref-architecture-integrations.png)


The following figure illustrates how Amazon Lex and Amazon OpenSearch Service help power the QnABot on AWS solution.

 **How Amazon Lex and Amazon OpenSearch Service help power the QnABot on AWS solution.** 

![\[arch data flow\]](http://docs.aws.amazon.com/solutions/latest/qnabot-on-aws/images/arch-data-flow.png)


Asking QnABot on AWS questions initiates the following processes:

1. The question gets processed and transcribed by Amazon Lex using NLU and Natural Language Processing (NLP) engines.

1. The solution initially trains the NLP engine to match a wide variety of possible questions and statements so that the Amazon Lex chatbot can accept almost any question a user asks. The Amazon Lex interaction model is set up with the following:
   +  **intents** - An intent represents an action that fulfills a user’s spoken request. Intents can optionally have arguments called *slots*. The solution uses *slots* to capture user input and fulfill the intent via a Lambda function.
   +  **sample utterances** - A set of likely spoken phrases mapped to the intents. This should include as many representative phrases as possible. The sample utterances specify the words and phrases users can say to invoke your intents. The solution updates the **sample utterances** with the various questions to train the chatbot to understand different end user’s input.

1. This question is then sent to Amazon OpenSearch Service. The solution attempts to match an end user’s request to the list of questions and answers stored in Amazon OpenSearch Service.
   + The QnABot on AWS uses full-text search to find the most relevant ranked document from the searchable index. Relevancy ranking is based on a few properties:
     +  **count** - How many search terms appear in a document.
     +  **frequency** - How often the specified keywords occur in a given document.
     +  **importance** - How rare or new the specified keywords are and how closely the keywords occur together in a phrase.
   + The closer the alignment between a question associated with an item and a question asked by the user, the greater the probability that the solution will choose that item as the most relevant answer. Noise words such as articles and prepositions in sentence construction have lower weighting than unique keywords.
   + The keyword filter feature helps the solution to be more accurate when answering questions, and to admit more readily when it doesn’t know the answer. The keyword filter feature works by using Amazon Comprehend to determine the part of speech that applies to each word you say to QnABot on AWS. By default, nouns (including proper nouns), verbs, and interjections are used as keywords. Any answer returned by QnABot on AWS must have questions that match these keywords, using the following (default) rule:
     + If there are one or two keywords, then all keywords must match.
     + If there are three or more keywords, then 75% of the keywords must match.
     + If QnABot on AWS can’t find any answers that match these keyword filter rules, then it will admit that it doesn’t know the answer rather than guessing an answer that doesn’t match the keywords. QnABot on AWS logs every question that it can’t answer so you can see them in the included Kibana Dashboard.
     + The Bot fulfillment Lambda function generates an Amazon OpenSearch Service query containing the transcribed question. The query attempts to find the best match from all the questions and answers you’ve previously provided, filtering items to apply the keyword filters and using Amazon OpenSearch Service relevance scoring to rank the results. Scoring is based on 1) matching the words in the end user’s question against the unique set of words used in the stored questions (`quniqueterms`), 2) matching the phrasing of the user’s question to the text of stored questions (nested field `questions.q`), and 3) matching the topic value assigned to the previous answer (if any) to increase the overall relevance score when the topic value (field `t`) matches. The following example code shows an Amazon OpenSearch query:

       ```
       "query":{
           "bool": {
               "filter": {
                   "match": {
                       "quniqueterms": {
                           "query": "<LIST_OF_IDENTIFIED_KEYWORDS>",
                           "minimum_should_match":
                                 "<ES_MINIMUM_SHOULD_MATCH SETTING>",
                           "zero_terms_query": "all"
                       }
                   }
               },
               "should": [
                   {
                       "match": {
                           "quniqueterms": {
                               "query": "<USER QUESTION>",
                               "boost": 2
                           }
                       }
                   },
                   {
                       "nested": {
                           "score_mode": "max",
                           "boost": "<ES_PHRASE_BOOST SETTING>",
                           "path": "questions",
                           "query": {
                               "match_phrase": {
                                   "questions.q": "<USER QUESTION>"
                               }
                           }
                       }
                   },
                   {
                       "match": {
                           "t": "<PREVIOUS_TOPIC>"
                       }
                   }
               ]
           }
       }
       ```