# brightprogrammer7/iallo architecture

> Architecture diagram of the GitHub repository brightprogrammer7/iallo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brightprogrammer7/iallo
- Repository: https://github.com/brightprogrammer7/iallo

## Overview

##### Main Components
- Client Communication:
- This covers inbound/outbound call handling for both phone and WhatsApp. Note that Twilio is used for phone calls, while EC2 (AWS) handles WhatsApp integration.
- Infra/API Layer:
- This layer manages the real-time routing and coordination of calls. The “Realtime-twilio-inbound-outbound” folder contains Python scripts (inbound.py and outbound.py) that implement these interactions.
- Backend Processing:
- Located primarily in the “CallBot” module (with files like ai.py, ai+voice.py, and variations) where AI functions and voice processing activities occur. This is the heart of AI-powered conversation, leveraging OpenAI’s Realtime API.
- External Integrations & Agent Tools:
- Integration with other services (Google Sheets, Calendar, Gmail) is mentioned for agent productivity. Represent these as external systems that interact with the backend.
- Dashboard/Frontend:
- The “Website” directory contains the dashboard’s HTML, CSS, and JavaScript files (e.g., index.html, dashboard.html) for configuring the assistant, setting model parameters, and managing the interaction flow.
- Desktop Application:
- The “DesktopApp.py” file builds a Tkinter-based GUI that allows users to enter phone numbers and view real-time logs.
- Supporting Assets:
- Additional files like “data.json”, “config.json”, and the audio cache in the “CallBot” folder support configuration management and media file storage.

##### Relationships and Interactions
- From Twilio, show that the calls are directed to the Infra/API layer (Realtime processing scripts).
- The API layer then sends requests to the backend (CallBot) for processing voice, AI interactions, and storing audio caches.
- The backend communicates with external AI (OpenAI Realtime API) for natural language understanding, transcription (STT/TTS) and conversation logic.
- The frontend dashboard (Website) interacts with the backend to reflect current configuration and call status.
- Lastly, the Desktop App sits as an alternate client interface, directly interfacing with backend logs and control flows.

##### Architectural Patterns and Design Principles
- Modular Design: The separation into different folders (CallBot, Realtime-twilio-inbound-outbound, Website, etc.) shows clear modular boundaries.
- Separation of Concerns: Distinct responsibilities are assigned to handling voice calls, data routing, AI processing, and presenting dashboards.
- Real-time Communication: Emphasis on short-lived, real-time API calls for voice processing.
- Extensibility: Allowing for future integrations and additional features (bulk CSV uploads, multi-platform plugins) as indicated in the README.

##### Relevant Technologies and Frameworks
- Programming Language: Python (all backend and integration layers)
- Voice Integration: Twilio Voice with Media Streams; additionally, AWS is involved for WhatsApp handling.
- AI Services: OpenAI Realtime API for natural language processing, speech-to-text, and text-to-speech.
- Frontend: Standard web technologies (HTML, CSS, JavaScript) for the dashboard.
- Desktop Interface: Tkinter for the standalone desktop application.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Communication Layer
    subgraph "Client Communication"
        PC["Phone Call"]:::client
        WC["WhatsApp Communication"]:::client
    end

    %% External Communication Services
    PC -->|"uses"| TW["Twilio"]:::external
    WC -->|"via"| AWS["AWS (WhatsApp Integration)"]:::external

    %% Infra/API Layer with Realtime Scripts
    subgraph "Infra/API Layer"
        InboundScript["Inbound Script (inbound.py)"]:::infra
        OutboundScript["Outbound Script (outbound.py)"]:::infra
        InboundScript -->|"processes"| OutboundScript
    end

    TW -->|"routes"| InboundScript
    AWS -->|"routes"| OutboundScript

    %% Backend Processing (CallBot)
    Backend["Backend Processing (CallBot)"]:::backend
    OutboundScript -->|"forwards to"| Backend

    %% CallBot Modules within Backend
    subgraph "CallBot Modules"
        AI["AI Module (ai.py)"]:::backend
        AI_Voice["AI+Voice Module (ai+voice.py)"]:::backend
        AI_Voice_Fast["AI+Voice Fast Module (ai+voice+fast.py)"]:::backend
        AI_Voice_Fast_Bot["AI+Voice Fast Bot Module (ai+voice+fast+bot.py)"]:::backend
        HearReadAI["Hear&Read&AI Module (hear&read&ai.py)"]:::backend
        AI -->|"calls"| AI_Voice
        AI_Voice -->|"calls"| AI_Voice_Fast
        AI_Voice_Fast -->|"calls"| AI_Voice_Fast_Bot
        AI_Voice_Fast_Bot -->|"calls"| HearReadAI
    end

    Backend -->|"triggers"| AI

    %% External Integrations and AI Service
    ExternalAI["OpenAI Service"]:::integration
    AgentTools["Agent Tools (GoogleSheets,Calendar,Gmail)"]:::integration
    Backend -->|"calls"| ExternalAI
    Backend -->|"updates"| AgentTools

    %% Supporting Assets
    subgraph "Supporting Assets"
        CallBotConfig["CallBot Config"]:::assets
        WebsiteConfig["Website Config"]:::assets
        AudioCache["Audio Cache"]:::assets
    end
    Backend -->|"uses"| CallBotConfig
    Backend -->|"stores media in"| AudioCache

    %% Dashboard/Frontend and Desktop Application
    Dashboard["Dashboard (Frontend)"]:::frontend
    DesktopApp["Desktop App (Tkinter)"]:::desktop
    Dashboard -->|"configures"| Backend
    Backend -->|"status to"| Dashboard
    DesktopApp -->|"monitors"| Backend

    %% Click Events
    click InboundScript "https://github.com/brightprogrammer7/iallo/blob/main/Realtime-twilio-inbound-outbound/inbound.py"
    click OutboundScript "https://github.com/brightprogrammer7/iallo/blob/main/Realtime-twilio-inbound-outbound/outbound.py"
    click WC "https://github.com/brightprogrammer7/iallo/blob/main/WhatsappBot.py"
    click AI "https://github.com/brightprogrammer7/iallo/blob/main/CallBot/ai.py"
    click AI_Voice "https://github.com/brightprogrammer7/iallo/blob/main/CallBot/ai+voice.py"
    click AI_Voice_Fast "https://github.com/brightprogrammer7/iallo/blob/main/CallBot/ai+voice+fast.py"
    click AI_Voice_Fast_Bot "https://github.com/brightprogrammer7/iallo/blob/main/CallBot/ai+voice+fast+bot.py"
    click HearReadAI "https://github.com/brightprogrammer7/iallo/blob/main/CallBot/hear&read&ai.py"
    click Dashboard "https://github.com/brightprogrammer7/iallo/tree/main/Website/"
    click DesktopApp "https://github.com/brightprogrammer7/iallo/blob/main/DesktopApp.py"
    click CallBotConfig "https://github.com/brightprogrammer7/iallo/blob/main/CallBot/data.json"
    click WebsiteConfig "https://github.com/brightprogrammer7/iallo/blob/main/Website/config.json"
    click AudioCache "https://github.com/brightprogrammer7/iallo/tree/main/CallBot/audio_cache/"

    %% Style Classes
    classDef client fill:#e0f7fa,stroke:#00796b,stroke-width:2px;
    classDef external fill:#ffccbc,stroke:#d84315,stroke-width:2px;
    classDef infra fill:#e1bee7,stroke:#8e24aa,stroke-width:2px;
    classDef backend fill:#f0f4c3,stroke:#afb42b,stroke-width:2px;
    classDef frontend fill:#c5cae9,stroke:#3949ab,stroke-width:2px;
    classDef desktop fill:#ffe082,stroke:#ff8f00,stroke-width:2px;
    classDef assets fill:#d7ccc8,stroke:#6d4c41,stroke-width:2px;
    classDef integration fill:#b2dfdb,stroke:#00796b,stroke-width:2px;

    class PC,WC client;
    class TW,AWS external;
    class InboundScript,OutboundScript infra;
    class Backend,AI,AI_Voice,AI_Voice_Fast,AI_Voice_Fast_Bot,HearReadAI backend;
    class Dashboard frontend;
    class DesktopApp desktop;
    class CallBotConfig,WebsiteConfig,AudioCache assets;
    class ExternalAI,AgentTools integration;
```
