Tags:

• aura-groot

Categories:

• components
• architecture

Aura Groot

Introduction

aura-groot is the main component in charge of handling the distributed architecture of Aura. It is responsible for the communication between each channel and its corresponding skill, keeping track of all the communication process, but introducing a minimal interference on it.

aura-groot main role includes:

• It is the component in charge of making the decision about what is the best bot to answer the user’s request and routing the request to the corresponding skill (bot).

• It is able to map configurable input parameters such as the channel that sent the request, user type, previous requests stored in the context, utterance, etc. with a specific domain. The OB will be able to configure the parameters used for the routing process.

Currently, routing is done only by channels or group of channels (no configuration options are available).

Aura Groot components

aura-groot contains two main components:

• Middlewares: software components in charge of the message flow.
• Recognizers: specific type of middlewares that are executed in a certain stage of the message flow.

Access to the corresponding sections to find detailed information regarding these components.

Aura Groot architecture

The first diagram shows all the components running in aura-groot.

The following diagram includes the messages flow through aura-groot.

Aura Groot configuration and operation

Find out the environment variables included in the aura-groot component here.

The operation of aura-groot is described in the document Aura Groot operational flows.

ConversationId handling

aura-groot uses groot-channel conversation identifier to track the conversation with the user and the use case with the skill. It is a string generated by the channel and is unique for each conversation. The groot-channel is sent in the incoming request to aura-groot in the conversationId field of the message object.

Additionally, it adds conversationReference inside. In this way, aura-groot only has to manage a single conversation and avoids synchronizing two different conversations. Doing so, accesses from aura-groot to the database are reduced.

This change implies a modification in the process the BotFramework works with a conversation, in two different documents which are updated separately. But, on the contrary, the advantage is a most efficient and secure way of working.

sequenceDiagram
title: BEFORE-DIRE-STRAITS

    actor Channel
    participant AuraGroot #ebdff7
    participant AuraBot #ebdff7

    Channel ->> AuraGroot: request message1
    AuraGroot ->> AuraGroot: create targetSkill in groot-channel
    AuraGroot ->> AuraGroot: save conversationReference in groot-channel
    AuraGroot ->> AuraBot: request message1
    AuraBot -->> AuraGroot: response message1
    AuraGroot ->> AuraGroot: load conversationReference in groot-channel
    AuraGroot -->> Channel: response message1
    AuraBot -->> AuraGroot: response endOfConversation
    AuraGroot ->> AuraGroot: load conversationReference in groot-channel
    AuraGroot ->> AuraGroot: delete targetSkill

    Channel ->> AuraGroot: request message2
    AuraGroot ->> AuraGroot: create targetSkill in groot-channel
    AuraGroot ->> AuraGroot: save conversationReference in groot-channel
    AuraGroot ->> AuraBot: request message2
    AuraBot -->> AuraGroot: response message2
    AuraGroot ->> AuraGroot: load conversationReference in groot-channel
    AuraGroot -->> Channel: response message2
    AuraBot -->> AuraGroot: response endOfConversation
    AuraGroot ->> AuraGroot: load conversationReference in groot-channel
    AuraGroot ->> AuraGroot: delete targetSkill

Aura Groot endpoints

Path	Method	Description
/api/messages/	POST	Incoming requests of channels or aura-bridge
/refresh/	POST	Update skills and channels. Data: {"changes": ["skills", "channels"]}. You can use “skills” and/or “channels” or neither of them. In the last case, all will be updated.
/api/skills/*	POST	Endpoints of Direct Line API for skills can exchange messages with aura-groot. The path where the skills will return the answers is configured in the environment variable AURA_SKILLS_RESPONSE_PATH, by default, /api/skills.
/healthz	GET	Monitoring endpoint. Healthcheck endpoint to validate if the server is up and running, only available from local network
/shutdown	GET	Monitoring endpoint. Wait until shutdown (Kubernetes lifecycle).
/heapSnapshot	GET	Endpoint that must be called internally directly accessing to the aura-groot pod. It stores in Aura Azure Storage Account a copy of the heap memory of the pod. It is useful to debug memory leaks.
/heapStatistics	GET	Endpoint that must be called internally directly accessing to the aura-groot pod. It returns the heap memory statistics of the pod.

These endpoints do not need to be defined in the plugin swagger, since they are supplied by the aura-groot core. Specific routes are defined in https://github.com/Telefonica/aura-distributed-bot/blob/main/master/packages/aura-groot/src/modules/server/routes.ts.

Postman collection

Aura Platform Team has generated a Postman collection for simulations over Aura distributed architecture: Aura distributed Postman collection.