# akiani/aidialer architecture

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

- Interactive diagram: https://gitdiagram.com/akiani/aidialer
- Repository: https://github.com/akiani/aidialer

## Overview

##### Project type and purpose
- This is a full-stack, streaming AI phone-call application (“AI Dialer”) built around Twilio’s voice API, a FastAPI back end, a Streamlit front end, and multiple AI services (STT, LLM, TTS) working in concert to deliver low-latency, interruptible calls.
- The goal is to place or receive calls via Twilio, stream audio to/from callers over WebSocket, transcribe speech in real time, feed text to an LLM (OpenAI or Anthropic), synthesize voice responses (Deepgram or ElevenLabs), and send them back to the caller.

##### File structure
Top-level files and directories:
- app.py – FastAPI server entrypoint
- services/ – modules that wrap external APIs and internal event handling
- call_context.py – per-call state management
- event_emmiter.py – pub/sub for audio & control events
- llm_service.py – text-to-text LLM orchestration
- transcription_service.py – real-time speech-to-text
- tts_service.py – text-to-speech output
- stream_service.py – audio chunk management over WS
- functions/ – Twilio webhook “function calls” invoked by the LLM for actions like end_call and transfer_call
- ui/streamlit_app.py – lightweight Streamlit UI to initiate calls and watch progress
- logger_config.py, settings.json, .env.example – configuration and logging
- examples/ – sample audio and screenshot

##### Key points from the README
- FastAPI exposes endpoints for Twilio ML webhooks and WebSockets.
- Twilio both triggers incoming-call webhooks and streams audio bi-directionally via WS attachments.
- The system is built for streaming→interruptibility: it handles “end of utterance” events, mid-sentence interruptions, and dynamic function calls.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Telephony Layer
    subgraph "Telephony Layer"
        classDef telephony fill:#d4f8d4,stroke:#333,stroke-width:1px
        Twilio["Twilio Phone Service"]:::telephony
        IncomingWebhook["FastAPI HTTP /incoming"]:::telephony
        WebSocketEndpoint["FastAPI WS /ws"]:::telephony
    end

    %% Streaming Pipeline
    subgraph "Streaming Pipeline"
        classDef pipeline fill:#d4e3f7,stroke:#333,stroke-width:1px
        StreamService["Stream Service\n(audio chunk mgmt)"]:::pipeline
        EventEmitter["Event Bus\n(pub/sub)"]:::pipeline
        CallContext["Call Context Manager"]:::pipeline
    end

    %% AI Services
    subgraph "AI Services"
        classDef ai fill:#f7d4b6,stroke:#333,stroke-width:1px
        TranscriptionService["STT Service\n(Deepgram)"]:::ai
        LLMService["LLM Service\n(OpenAI/Anthropic)"]:::ai
        TTSService["TTS Service\n(ElevenLabs/Deepgram)"]:::ai
    end

    %% Control Plane
    subgraph "Control Plane"
        classDef control fill:#e0e0e0,stroke:#333,stroke-width:1px
        FastAPIApp["FastAPI Server\n(REST & WS)"]:::control
        Functions["Function-Routing Layer"]:::control
        manifest["function_manifest.py"]:::control
        end_call["end_call.py"]:::control
        transfer_call["transfer_call.py"]:::control
        StreamlitUI["Streamlit UI"]:::control
        logger["logger_config.py"]:::control
        settings["settings.json"]:::control
        env[".env.example"]:::control
    end

    %% Connections
    Twilio -->|"HTTP Webhook"| IncomingWebhook
    IncomingWebhook -->|"returns TwiML to connect WS"| WebSocketEndpoint
    WebSocketEndpoint -->|"audio chunks over WS"| StreamService
    StreamService -->|"publishes audio frame"| EventEmitter
    EventEmitter -->|"on_end_of_utterance"| TranscriptionService
    TranscriptionService -->|"transcript JSON"| EventEmitter
    EventEmitter -->|"text input"| LLMService
    LLMService -->|"function call or text"| Functions
    Functions -->|"action trigger"| CallContext
    LLMService -->|"text response"| TTSService
    CallContext -->|"state info"| LLMService
    TTSService -->|"audio chunks"| StreamService
    StreamService -->|"audio chunks over WS"| WebSocketEndpoint
    WebSocketEndpoint -->|"to Twilio"| Twilio

    %% UI interactions
    StreamlitUI -->|"REST API calls"| FastAPIApp
    StreamlitUI -->|"subscribes WS events"| WebSocketEndpoint

    %% Click Events
    click FastAPIApp "https://github.com/akiani/aidialer/blob/main/app.py"
    click manifest "https://github.com/akiani/aidialer/blob/main/functions/function_manifest.py"
    click end_call "https://github.com/akiani/aidialer/blob/main/functions/end_call.py"
    click transfer_call "https://github.com/akiani/aidialer/blob/main/functions/transfer_call.py"
    click EventEmitter "https://github.com/akiani/aidialer/blob/main/services/event_emmiter.py"
    click CallContext "https://github.com/akiani/aidialer/blob/main/services/call_context.py"
    click TranscriptionService "https://github.com/akiani/aidialer/blob/main/services/transcription_service.py"
    click LLMService "https://github.com/akiani/aidialer/blob/main/services/llm_service.py"
    click TTSService "https://github.com/akiani/aidialer/blob/main/services/tts_service.py"
    click StreamService "https://github.com/akiani/aidialer/blob/main/services/stream_service.py"
    click StreamlitUI "https://github.com/akiani/aidialer/blob/main/ui/streamlit_app.py"
    click logger "https://github.com/akiani/aidialer/blob/main/logger_config.py"
    click settings "https://github.com/akiani/aidialer/blob/main/settings.json"
    click env "https://github.com/akiani/aidialer/blob/main/.env.example"

    %% Styles
    class Twilio,IncomingWebhook,WebSocketEndpoint telephony
    class StreamService,EventEmitter,CallContext pipeline
    class TranscriptionService,LLMService,TTSService ai
    class FastAPIApp,Functions,manifest,end_call,transfer_call,StreamlitUI,logger,settings,env control
```
