Unified Architecture Overview

Service Configuration and Business Management Integration

---

Executive Summary

This document provides comprehensive technical documentation for the WIIL Platform's unified architecture, bridging the Service Configuration system with the Business Management system. The architecture enables organizations to deploy AI-powered conversational agents that leverage business services to conduct intelligent customer conversations, ultimately driving transactional outcomes such as appointments, reservations, and orders.

The central integration point is the Conversations entity, which connects:

• Agents in Deployment Configurations (from Service Configuration)
• Business Customers (end users)
• Transactional Operations (Service Appointments, Reservations, Menu Orders, Product Orders)

---

1. Introduction

1.1 Purpose

The WIIL Platform integrates two major architectural domains:

1. Service Configuration: Manages the deployment of AI agents through instruction configurations, deployment configurations, and communication channels.

2. Business Management: Manages business entities (services, resources, menus, products) and their transactional operations.

The Conversations entity serves as the bridge, enabling AI agents to leverage business services in real-time customer interactions.

1.2 Scope

This documentation covers:

• Service Configuration components and their role in agent deployment
• Business Management components and their catalog/transaction model
• The Conversations entity as the central integration point
• Data flow between both systems
• Schema definitions for conversation handling

1.3 Intended Audience

• Solution Architects
• Platform Engineers
• Backend Developers
• Integration Specialists
• Technical Project Managers

---

2. Unified Architecture Overview

2.1 High-Level Architecture

2.2 Integration Points

The architecture has three key integration points:

Integration Point	Connects	Purpose
Conversations	Agents ↔ Customers	Central hub for AI-powered customer interactions
Instruction Configurations	Service Config ↔ Conversations	Defines agent behavior in conversations
Transactions	Conversations ↔ Business Entities	Creates business outcomes from conversations

2.3 Design Principles

Unified Customer Experience: Customers interact through Conversations, unaware of the underlying system complexity.

Separation of Configuration and Execution: Service Configuration defines how agents behave; Business Management defines what they can do.

Transactional Outcomes: Every conversation can result in measurable business transactions.

Multi-Channel Support: Conversations span multiple channel types (OTT Chat, Telephony, SMS, Email).

---

3. Service Configuration Domain

3.1 Overview

The Service Configuration domain manages the deployment and behavior of AI agents within the platform.

3.2 Agent Configurations

Purpose: Define AI agent capabilities and characteristics—the technical setup that powers agent deployments.

Key Attributes:

• AI model selection (modelId, modelProvider)

Relationship to Deployments:

• One Agent Configuration can power multiple Deployment Configurations
• Combined with Instruction Configurations to create deployable agents
• Examples: "Sales Agent", "Support Agent", "Booking Agent"

For API details, see Agent Configurations API Reference.

3.3 Instruction Configurations

Purpose: The heart of agent behavior—defines the prompts, guidelines, and contextual instructions that govern how agents conduct conversations.

Key Attributes:

• System prompts
• Conversation guidelines
• Domain-specific instructions
• Compliance rules
• Escalation criteria

Relationship to Conversations:

• Referenced by instruction_config_id in Conversation records
• Guides AI behavior during customer interactions

For API details, see Instruction Configurations API Reference.

3.4 Deployment Channels

Purpose: Manage communication channels for agent deployments.

Channel Types:

• OTT (Voice and Chat)
• Telephony
• SMS

For API details, see Deployment Channels API Reference.

3.5 Deployment Configurations

Purpose: Combines agent configurations with instruction configurations to create deployable units.

Key Attributes:

• Deployment identifier
• Agent configuration reference
• Instruction configuration reference
• Channel configuration

Relationship to Conversations:

• Referenced by deployment_config_id in Conversation records
• Determines which agent handles the conversation

For API details, see Deployment Configurations API Reference.

3.6 Management Modules

The platform provides specialized management modules:

Module	Manages	Receives Data From
Appointment Management	Business Service catalog	Service Appointments
Reservation Management	Reservable Assets catalog	Reservations
Menu Management	Menu Category/Items catalog	Menu Orders
Product Management	Product Category/Product catalog	Product Orders
Property Management	Property Category/Address/Listing catalog	Property Inquiries

3.7 Advanced Service Configuration

Purpose: Enables voice-powered conversations through end-to-end processing pipelines.

Key Components:

Component	Purpose
Provisioning Chain Configuration	STT → Agent → TTS processing pipeline
Speech-to-Text (STT)	Voice input transcription (Deepgram, OpenAI Whisper, Cartesia)
Text-to-Speech (TTS)	Natural voice synthesis (ElevenLabs, Cartesia, OpenAI)

Relationship to Conversations:

• Referenced by stt_model_id and tts_model_id in Conversation records
• Enables TELEPHONY_CALL conversation types

For detailed documentation, see Translation Services.

3.8 Translation Services

Purpose: Real-time multilingual voice translation for cross-language communication.

Key Components:

Component	Purpose
Translation Chain Configuration	STT → Translation → TTS pipeline for language pairs
Translation Sessions	Live voice-to-voice translation sessions
Translation Participants	Multi-participant support with language isolation
Knowledge Sources	Knowledge bases for translation accuracy

Capabilities:

• Bidirectional translation (both parties hear translated speech)
• Multi-participant sessions (3+ participants, each in native language)
• Full transcription logging

For detailed documentation, see Translation Services.

---

4. Business Management Domain

4.1 Overview

The Business Management (Business Mgt) domain manages business entities and their associated catalogs.

4.2 Business Entities

Business Mgt Manages:

Entity	Purpose	Transaction Type
Business Service	Bookable services (salon, clinic, consulting)	Service Appointment
Reservable Assets (Resources)	Bookable resources (tables, rooms, equipment)	Reservations
Menu Category and MenuItems	Food/beverage offerings	Menu Order
Product Category and Product	Retail products	Product Order
Property Category	Property classification for real estate	-
Property Address	Property location information	-
Property Listing	Real estate listings (residential, commercial, land)	Property Inquiry

4.3 Customer

Purpose: Represents business customers who interact through conversations and create transactions.

Key Attributes:

• Identity (name, email, phone)
• Profile preferences and tags
• Transaction history references
• Lifecycle status (ACTIVE, INACTIVE)
• First and last contact dates

Relationships:

• Referenced by customer_id in Conversation records
• Referenced by customer_id in all transaction types
• Linked to Service Appointments, Reservations, Menu Orders, Product Orders, Property Inquiries

For API details, see Customer API Reference.

4.4 Transactional Entities

Transactions are created as outcomes of Conversations:

Transaction	Uses Catalog	Created Via
Service Appointment	Business Service	Conversation with AI Agent
Reservations	Reservable Assets	Conversation with AI Agent
Menu Order	Menu Category/Items	Conversation with AI Agent
Product Order	Product Category/Product	Conversation with AI Agent
Property Inquiry	Property Listing	Conversation with AI Agent

---

5. Conversations - The Integration Hub

5.1 Overview

Conversations is the central entity that bridges Service Configuration and Business Management. It represents a single interaction session between a Business Customer and an AI Agent deployed via the Service Configuration system.

5.2 Conversation Initiation Flow

Business Customer
      │
      │ Initiates contact via Channel
      ▼
┌─────────────────┐
│ Channel Handler │──────▶ Resolves deployment_config_id
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Create          │
│ Conversation    │──────▶ Links instruction_config_id
└────────┬────────┘        Links customer_id
         │
         ▼
┌─────────────────┐
│ AI Agent        │──────▶ Uses Instruction Configuration
│ (via Deployment)│        Uses Business Catalogs
└────────┬────────┘
         │
         │ Conducts conversation
         │ Creates transactions as needed
         ▼
┌─────────────────┐
│ Transaction     │──────▶ Service Appointment / Reservation
│ Created         │        Menu Order / Product Order
└─────────────────┘

5.3 Transaction Creation Flow

Conversation (Active)
      │
      │ Customer expresses intent
      ▼
┌─────────────────┐
│ AI Agent        │──────▶ Queries Business Catalog
│ Processes       │        (via Business Mgt)
└────────┬────────┘
         │
         │ Identifies matching service/resource/product
         ▼
┌─────────────────┐
│ Confirm with    │
│ Customer        │
└────────┬────────┘
         │
         │ Customer confirms
         ▼
┌─────────────────┐
│ Create          │──────▶ Service Appointment
│ Transaction     │        Reservation
└────────┬────────┘        Menu Order
         │                 Product Order
         ▼
┌─────────────────┐
│ Management      │──────▶ Appointment Management
│ Module          │        Reservation Management
│ Receives Data   │        Menu Management
└─────────────────┘        Product Management

---

6. Telephony-Specific Features

6.1 Call Transfer

For telephony conversations, the platform supports call transfers:

{
  transfer_type?: 'blind' | 'warm',    // Unattended or attended transfer
  transfer_target: string,              // Target phone number
  transfer_initiated_at?: number,       // When transfer started
  transfer_completed_at?: number,       // When transfer completed
  transfer_status: 'pending' | 'completed' | 'failed' | 'returned',
  transfer_reason?: string              // Why transfer occurred
}

6.2 Voice Configuration

Telephony conversations can specify:

• stt_model_id: Speech-to-Text model for transcription
• tts_model_id: Text-to-Speech model for voice synthesis
• resource_url: Recording or call detail URL

---

7. Operational Workflows

7.1 End-to-End Booking Workflow

1. Customer contacts business via phone/chat/web
                    │
                    ▼
2. Channel routes to Deployment Configuration
                    │
                    ▼
3. Conversation created with:
   • deployment_config_id
   • instruction_config_id
   • channel_id
   • customer_id (if known)
                    │
                    ▼
4. AI Agent (guided by Instructions) engages customer
                    │
                    ▼
5. Agent queries Business Catalogs:
   • Available services
   • Available time slots
   • Available resources
                    │
                    ▼
6. Customer selects and confirms
                    │
                    ▼
7. Transaction created:
   • Service Appointment / Reservation / Order
                    │
                    ▼
8. Conversation summarized and completed
                    │
                    ▼
9. Management Module processes transaction

7.2 Multi-Transaction Conversation

A single conversation can create multiple transactions:

Conversation: Restaurant Booking
      │
      ├──▶ Reservation (table for 4 at 7pm)
      │
      └──▶ Menu Order (pre-order appetizers)

---

8. Glossary

Term	Definition
Agent Configuration	Defines AI agent capabilities and characteristics (model selection, provider)
Business Customer	End user who interacts with the platform through conversations
Business Mgt	Business Management - manages business entity catalogs
Conversation	A single interaction session between a customer and an AI agent
Conversation Type	The channel medium (OTT_CHAT, TELEPHONY_CALL, SMS, EMAIL)
Deployment Channel	Communication channel for agent deployments (OTT, Telephony, SMS)
Deployment Configuration	Combined agent and instruction configuration for deployment
Instruction Configuration	Defines AI agent behavior during conversations
Management Module	Platform service that manages specific catalog and transaction types
Service Configuration	System for deploying and configuring AI agents
Transaction	Business outcome from a conversation (appointment, reservation, order)

---

9. Appendix

9.1 Conversation Status Values

Status	Description
ACTIVE	Conversation is ongoing
COMPLETED	Conversation ended normally
TRANSFERRED	Call was transferred to another party
ABANDONED	Customer left before completion
FAILED	Technical failure occurred

9.2 Conversation Summary Sentiments

Sentiment	Description
POSITIVE	Customer had a positive experience
NEUTRAL	Neither positive nor negative
NEGATIVE	Customer had a negative experience
MIXED	Combination of sentiments

9.3 Document Revision History

Version	Date	Author	Changes
1.0	2025	Architecture Team	Initial unified documentation

---

End of Document