Architecture

The Daily Conversation Reports Feature enables automated generation, storage, and retrieval of hourly conversation data per tenant. It consists of background jobs for report generation and API for on-demand access. This feature enhances observability and reporting capabilities within a multi-tenant virtual agent platform.

For the technical details please check the API Reference.

1. Enabling the Feature

The system uses a multi-tenant architecture, allowing the daily conversation reporting feature to be enabled or disabled individually for each tenant. This configuration is managed by the host user through tenant feature settings, which control both report generation and access rights.

Additionally, data retention can be configured per tenant to span from 1 to 3 months, depending on preference. Reports are accessible only to tenants with the feature enabled, and access is strictly governed by tenant authentication and permissions.

2. Report Generation Process

This sequence diagram outlines the logic and flow of a nightly background job executed by the Knovvu Virtual Agent (VA). The job is responsible for generating and storing hourly conversation data chunks for each tenant who has the reporting enabled.

Execution Flow

1. A nightly scheduler initiates a background job within the Virtual Agent (VA), processing all tenants with the reporting feature enabled.

2. For each tenant, the system iterates through all 24 hours of the previous day, retrieving conversation data from the database in JSON format.

3. The retrieved JSON chunks are then compressed into .zip format to optimize both storage and transfer.

4. Each zipped chunk is uploaded to MinIO, following a clear and consistent naming convention: daily-report-<yyyy-mm-dd>-<hour>.zip

3. Daily Report Fetching

This sequence diagram describes the on-demand data retrieval process used by clients to fetch hourly conversation report chunks for a given UTC day. The API supports both compressed and uncompressed formats, enabling efficient and flexible access.

1. The client initiates a GET request (one for each hour from 0 to 23) to retrieve hourly conversation report chunks, specifying:

   • utcDay in UTC format (e.g., 2025-04-22)
   • utcHour (e.g., 15)
   • compressed (Boolean flag indicating whether the response should be zipped)

2. Upon receiving a request, the Virtual Agent validates the client's authentication token and checks tenant-specific permissions to access the report data.

3. Once authorized, the VA fetches the corresponding report file from MinIO, containing the hourly conversation data.

4. If the client requests a compressed version (compressed=true), the VA returns the zipped file directly, including metadata in the HTTP headers.
   If compressed=false, the VA extracts and parses the zipped content, returning the uncompressed JSON data in the response body.

Key Components

• Virtual Agent: Initiates and executes the nightly job, handles validation, data processing, and response logic for both scheduled and on-demand report access.
• Client: Requests conversation report data by specifying the desired UTC date, hour, and response format. May integrate the data into dashboards, reporting tools, or analytics systems.
• Database: Stores all conversation logs. Queried hourly by tenant for both report generation and fallback retrievals.
• MinIO: Serves as the object storage system for saving compressed hourly report files, enabling scalable and cost-effective access.