Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      External APIs                          │
│  (Gemini, OpenAI, Hume, Twilio, Plivo, Gmail, etc.)         │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────┐
│                   API Gateway Layer                         │
│         FastAPI (http://localhost:8010)                     │
│                                                             │
│  ├── REST API Endpoints (/api/agents, /api/calls, etc.)     │
│  ├── WebSocket Streaming (/ws/stream)                       │
│  └── Webhook Receivers (/webhook/twilio, etc.)              │
└─────────┬──────────┬──────────┬──────────┬─────────────────-┘
          │          │          │          │
    ┌─────▼──┐  ┌────▼────┐ ┌──▼────┐ ┌──▼────┐
    │ Agent  │  │  Call   │ │Org &  │ │Batch  │
    │Service │  │ Service │ │Auth   │ │Calls  │
    └─────┬──┘  └────┬────┘ └──┬────┘ └──┬────┘
          │          │         │         │
    ┌─────▼──────────▼─────────▼─────────▼──────┐
    │                                           │
    │    AI Bridges Layer                       │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
    │  │  Gemini  │ │  OpenAI  │ │   Hume   │   │
    │  └──────────┘ └──────────┘ └──────────┘   │
    │                                           │
    └─────────────┬─────────────────────────────┘
                  │
    ┌─────────────▼──────────────────┐
    │   Communication Layer          │
    │  ┌──────────┐ ┌──────────┐     │
    │  │  Twilio  │ │  Plivo   │     │
    │  └──────────┘ └──────────┘     │
    │  ┌──────────────────────────┐  │
    │  │  LiveKit (RTC Media)     │  │
    │  └──────────────────────────┘  │
    └─────────────┬──────────────────┘
                  │
    ┌─────────────▼──────────────────┐
    │  Integration Layer (MCP)       │
    │  ┌──────────┐ ┌──────────┐     │
    │  │ Telegram │ │  Gmail   │     │
    │  └──────────┘ └──────────┘     │
    │  ┌──────────┐ ┌──────────┐     │
    │  │WhatsApp  │ │ Shopify  │     │
    │  └──────────┘ └──────────┘     │
    └─────────────┬──────────────────┘
                  │
    ┌─────────────▼──────────────────┐
    │  Data Persistence Layer        │
    │  ┌──────────────────────────┐  │
    │  │    Supabase (PostgreSQL) │  │
    │  │  (Organizations, Agents, │  │
    │  │   Calls, Schedules)      │  │
    │  └──────────────────────────┘  │
    └────────────────────────────────┘

class AgentService:
    def create_agent(self, config: AgentConfig) -> Agent
    def get_agent(self, agent_id: str) -> Agent
    def update_agent(self, agent_id: str, config: AgentConfig) -> Agent
    def delete_agent(self, agent_id: str) -> None

def initiate_call(self, call_request: OutboundCallRequest) -> Call
def handle_incoming_call(self, twilio_data: dict) -> TwiMLResponse
def process_call_stream(self, websocket: WebSocket, call_id: str) -> None
def end_call(self, call_id: str) -> None

class AIBridge:
    async def process_message(self, message: str, context: ConversationContext) -> str
    async def stream_response(self, message: str) -> AsyncIterator[str]
    def set_system_prompt(self, prompt: str) -> None
    async def execute_tool(self, tool_name: str, args: dict) -> Any

MCP Client (in AgentService)
     │
     └─► MCP Server Process
              │
              ├─► Tool: send_email
              ├─► Tool: read_email
              ├─► Tool: send_message
              └─► Tool: read_message

-- Organizations
CREATE TABLE organizations (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

-- Agents
CREATE TABLE agents (
  id UUID PRIMARY KEY,
  organization_id UUID REFERENCES organizations,
  name TEXT NOT NULL,
  ai_provider TEXT,
  system_prompt TEXT,
  created_at TIMESTAMP
);

-- Calls
CREATE TABLE calls (
  id UUID PRIMARY KEY,
  agent_id UUID REFERENCES agents,
  from_phone TEXT,
  to_phone TEXT,
  status TEXT,
  duration INTEGER,
  recording_url TEXT,
  created_at TIMESTAMP
);

-- Scheduled Calls
CREATE TABLE scheduled_calls (
  id UUID PRIMARY KEY,
  agent_id UUID REFERENCES agents,
  phone_number TEXT,
  scheduled_time TIMESTAMP,
  status TEXT,
  cron_expression TEXT
);

-- Batch Calls
CREATE TABLE batch_calls (
  id UUID PRIMARY KEY,
  organization_id UUID REFERENCES organizations,
  file_url TEXT,
  status TEXT,
  total_calls INTEGER,
  completed_calls INTEGER,
  created_at TIMESTAMP
);

1. Client establishes WebSocket connection
2. Audio frames received in real-time
3. Frames sent to AI provider
4. Response streamed back to client
5. Text-to-speech conversion
6. Audio sent to phone

API Request
    │
    ├─► Header: Authorization: Bearer <token>
    │
    ├─► Verify Token (Supabase JWT)
    │
    └─► Extract User & Organization