# JB Manager Architecture

This document explains the inner workings of the JB Manager.

### Architecture

All the services are generic i.e. they are designed for multiple bots or use cases. The only customization that exists lies in the tiny bot code (finite state machine code) which is published by the Studio.

![](/files/8C46GA3Jwz2Mdp9Y0HKt) To change this diagram edit this [file](https://github.com/OpenNyAI/Jugalbandi-Manager/blob/main/docs/assests/JB-Manager-Architecture.drawio.png)

### DB Structure

**Bot**

bot\_id (e.g. "12345") is at the highest level. All other entries like person, sessions are against a particular bot. We support multiple bots from the same backend.

**User**

A user needs to be registered for the bot. Phone Number & Bot ID make the user unique.

**Session**

This table stores the state (stage in the workflow) and variables for every user. We maintain session for 24 hours. After that a fresh conversation starts.

**Turn**

Every message received from the user creates a new turn in the conversation. Against one user message, we can have multiple bot responses.

**Message**

Every message received or sent is logged to the DB.

### Services

#### API

Provides APIs to interact with JB Manager. Here are the top buckets of APIs:

1. Callback from channels like WhatsApp or Telegram
2. JB Studio like publishing the bot
3. Managing bots changing their states and variables
4. Viewing chat logs and analytics
5. Triggering indexing jobs

**Callback**

1. Figure out `bot_id` based on the callback
2. Create person if doesn't exists. Fetch `pid`
3. Create `session_id` if session has expired (> 24 hours).
4. Creates `turn_id` for the new conversation
5. Create `msg_id`

#### Channel

Responsible for both input and output communication with the channel (WhatsApp / Telegram). It needs to handle channel specific API calls and rendering of UI messages (e.g. WhatsApp Flow, List & Buttons)

1. If media present in the message, fetch and upload to Azure.
2. Provides standard dialogues (list/buttons) for features that are common to all bots. It handles rendering (outbound) and the related user action. It let's Flow service know that the user has completed a dialogue.
   1. Language - It shows the dialog and saves the user's language preference
   2. Reset (not yet there)

In the inbound scenario:

* It mostly enqueues messages for the Language service
* Unless the message related to a dialogue (e.g. language), WhatsApp Flow or Button. In this case it directly talks to the Flow service.

In the outbound scenario:

* It mostly receives messages from the Language service.
* Unless the message is related to WhatsApp flow in which case Flow directly writes to it's queue.

#### Language

1. There are two flows:
   1. Receiving users message
   2. Sending the response to the user.

It's responsible for translating labels in case of interactives messages e.g. Lists & Buttons

We assume that all messages sent by the user obey the user's `preferred_language`.

For outbound messages, Language service will look at the message type from the Flow Service and then decide on the following:

1. If `text`
   1. Then fetch details about the turn -- In what mode did the user ask their question:
      1. If user asks in text / form / interactive, we respond in text
      2. If user asks in voice, we respond in voice + text -- Language service creates two inputs for Channel service
      3. In all other cases, send text
2. If `document`,
   1. Translate the caption
3. `image`
4. Translate the caption
5. If `interactive`
   1. Translate the text, header, footer
   2. Translate the labels for buttons

#### Flow

1. Retrieve session from DB based on session\_id. This provides it memory of the current state (stage of the workflow), variables.
2. Process the message via a finite state machine code (this code is generated in the Studio and pushed to the JB Manager)
   1. It can send multiple messages for every user message
   2. It can make API calls or use plugins
   3. The responses that it sends can include the following:
      1. Text
      2. Interactive - WhatsApp flow, List, Buttons
      3. Documents, Images
      4. Dialogues -- it uses keywords `language` to trigger Channel service into sending a standardized dialogue.
3. On complete (or logical pause in the workflow e.g. user input or plugin input), save the state and variables.

#### Retrieval

This fetches data from the Vector DB (PG Vector / Postgres) based on query and metadata if any. The metadata is used to create filter query to restrict the similarity search even further.

#### Indexer

This service receives input files (urls from Azure) and pre-processes them and indexes them into the Vector DB.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.jugalbandi.opennyai.org/building-with-jugalbandi/technical-guide/explanations/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.