# deepakchaudharigit/npcl-asterisk-ari-assistant architecture

> Architecture diagram of the GitHub repository deepakchaudharigit/npcl-asterisk-ari-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deepakchaudharigit/npcl-asterisk-ari-assistant
- Repository: https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant

## Overview

This repository is a Gemini-powered voice assistant with standalone interaction and an Asterisk telephony mode. The principal documented workflow is an incoming call handled by the real-time ARI server, which tracks a session and sets up external-media audio; audio and conversation are exchanged with Gemini Live for low-latency, interruptible voice responses. Separate audio, AI, tools, and security components provide processing and supporting capabilities. The README also documents standalone speech recognition, Gemini responses, and TTS. Some links reflect README-level capabilities; unsampled implementations and wiring are not inferred.

Main entry points: [`src/voice_assistant/ai/websocket_gemini_client.py`](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/websocket_gemini_client.py) (WebSocket Gemini client), [`src/voice_assistant/telephony/realtime_ari_handler.py`](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/telephony/realtime_ari_handler.py) (Realtime ARI handler), [`src/voice_assistant/security/security_manager.py`](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/security_manager.py) (Security manager), [`src/main.py`](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/main.py) (Standalone assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_realtime_server["Realtime server"]
  node_main["Standalone assistant<br/>[main.py]"]
end

subgraph group_telephony["Telephony and sessions"]
  node_ari["Realtime ARI handler"]
  node_external_media["External media"]
  node_session["Session manager<br/>[session_manager.py]"]
  node_legacy_ari["Legacy ARI handler<br/>[ari_handler.py]"]
  node_rtp["RTP streaming"]
end

subgraph group_audio["Audio processing"]
  node_realtime_audio["Realtime audio processor"]
  node_advanced_audio["Advanced audio processor"]
  node_speech_recognition["Speech recognition"]
  node_tts["Text to speech<br/>[text_to_speech.py]"]
end

subgraph group_ai["AI and tools"]
  node_live_client["Gemini Live client"]
  node_websocket_client["WebSocket Gemini client"]
  node_gemini_client["Gemini client<br/>[gemini_client.py]"]
  node_function_calling["Function calling"]
  node_prompts["Assistant prompts<br/>[npcl_prompts.py]"]
  node_weather["Weather tool<br/>[weather_tool.py]"]
end

subgraph group_security["Security"]
  node_security_manager["Security manager"]
  node_auth["Authentication<br/>[auth_manager.py]"]
  node_validator["Input validation<br/>[input_validator.py]"]
  node_rate_limiter["Rate limiting<br/>[rate_limiter.py]"]
  node_audit["Audit logging<br/>[audit_logger.py]"]
end

node_caller(("Caller"))
node_standalone_user(("Standalone user"))
node_asterisk["Asterisk PBX"]
node_google["Google Gemini"]

node_caller -->|"calls"| node_asterisk
node_asterisk -->|"sends events"| node_ari
node_realtime_server -->|"starts"| node_ari
node_ari -->|"creates and updates"| node_session
node_ari -->|"starts stream"| node_external_media
node_ari -->|"uses"| node_live_client
node_external_media -->|"processes audio"| node_realtime_audio
node_external_media -->|"exchanges audio"| node_live_client
node_external_media -->|"tracks session"| node_session
node_live_client -->|"streams conversation"| node_google
node_standalone_user -->|"speaks to"| node_main
node_main -->|"requests responses"| node_gemini_client
node_main -.->|"transcribes speech"| node_speech_recognition
node_main -.->|"speaks response"| node_tts
node_websocket_client -->|"processes audio"| node_advanced_audio
node_websocket_client -->|"dispatches calls"| node_function_calling
node_websocket_client -->|"uses"| node_prompts
node_websocket_client -->|"registers tool"| node_weather
node_websocket_client -.->|"streams audio"| node_rtp
node_live_client -->|"uses"| node_realtime_audio
node_security_manager -->|"authenticates"| node_auth
node_security_manager -->|"checks limits"| node_rate_limiter
node_security_manager -->|"validates input"| node_validator
node_security_manager -->|"records events"| node_audit
node_caller -.->|"uses legacy mode"| node_legacy_ari

click node_realtime_server "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/run_realtime_server.py"
click node_main "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/main.py"
click node_ari "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/telephony/realtime_ari_handler.py"
click node_external_media "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/telephony/external_media_handler.py"
click node_session "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/core/session_manager.py"
click node_legacy_ari "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/ari_handler.py"
click node_rtp "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/telephony/rtp_streaming_handler.py"
click node_live_client "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/gemini_live_client.py"
click node_websocket_client "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/websocket_gemini_client.py"
click node_gemini_client "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/gemini_client.py"
click node_function_calling "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/function_calling.py"
click node_prompts "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/npcl_prompts.py"
click node_weather "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/tools/weather_tool.py"
click node_realtime_audio "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/audio/realtime_audio_processor.py"
click node_advanced_audio "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/audio/advanced_audio_processor.py"
click node_speech_recognition "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/audio/speech_recognition.py"
click node_tts "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/audio/text_to_speech.py"
click node_security_manager "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/security_manager.py"
click node_auth "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/auth_manager.py"
click node_validator "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/input_validator.py"
click node_rate_limiter "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/rate_limiter.py"
click node_audit "https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/audit_logger.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_realtime_server,node_main,node_standalone_user toneBlue
class node_ari,node_external_media,node_session,node_legacy_ari,node_rtp toneAmber
class node_realtime_audio,node_advanced_audio,node_speech_recognition,node_tts toneMint
class node_live_client,node_websocket_client,node_gemini_client,node_function_calling,node_prompts,node_weather toneRose
class node_security_manager,node_auth,node_validator,node_rate_limiter,node_audit,node_caller,node_asterisk,node_google toneIndigo
```

## Components

### Entry points

- [Realtime server](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/run_realtime_server.py): `src/run_realtime_server.py`
- [Standalone assistant](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/main.py): `src/main.py`

### Telephony and sessions

- [Realtime ARI handler](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/telephony/realtime_ari_handler.py): `src/voice_assistant/telephony/realtime_ari_handler.py`
- [External media](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/telephony/external_media_handler.py): `src/voice_assistant/telephony/external_media_handler.py`
- [Session manager](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/core/session_manager.py): `src/voice_assistant/core/session_manager.py`
- [Legacy ARI handler](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/ari_handler.py): `src/ari_handler.py`
- [RTP streaming](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/telephony/rtp_streaming_handler.py): `src/voice_assistant/telephony/rtp_streaming_handler.py`

### Audio processing

- [Realtime audio processor](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/audio/realtime_audio_processor.py): `src/voice_assistant/audio/realtime_audio_processor.py`
- [Advanced audio processor](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/audio/advanced_audio_processor.py): `src/voice_assistant/audio/advanced_audio_processor.py`
- [Speech recognition](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/audio/speech_recognition.py): `src/voice_assistant/audio/speech_recognition.py`
- [Text to speech](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/audio/text_to_speech.py): `src/voice_assistant/audio/text_to_speech.py`

### AI and tools

- [Gemini Live client](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/gemini_live_client.py): `src/voice_assistant/ai/gemini_live_client.py`
- [WebSocket Gemini client](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/websocket_gemini_client.py): `src/voice_assistant/ai/websocket_gemini_client.py`
- [Gemini client](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/gemini_client.py): `src/voice_assistant/ai/gemini_client.py`
- [Function calling](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/function_calling.py): `src/voice_assistant/ai/function_calling.py`
- [Assistant prompts](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/ai/npcl_prompts.py): `src/voice_assistant/ai/npcl_prompts.py`
- [Weather tool](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/tools/weather_tool.py): `src/voice_assistant/tools/weather_tool.py`

### Security

- [Security manager](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/security_manager.py): `src/voice_assistant/security/security_manager.py`
- [Authentication](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/auth_manager.py): `src/voice_assistant/security/auth_manager.py`
- [Input validation](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/input_validator.py): `src/voice_assistant/security/input_validator.py`
- [Rate limiting](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/rate_limiter.py): `src/voice_assistant/security/rate_limiter.py`
- [Audit logging](https://github.com/deepakchaudharigit/npcl-asterisk-ari-assistant/blob/main/src/voice_assistant/security/audit_logger.py): `src/voice_assistant/security/audit_logger.py`

### Other components

- **Caller**
- **Standalone user**
- **Asterisk PBX**
- **Google Gemini**

## Connections

- Caller → Asterisk PBX: calls (evidence: `README.md`)
- Asterisk PBX → Realtime ARI handler: sends events (evidence: `README.md`)
- Realtime server → Realtime ARI handler: starts (evidence: `src/run_realtime_server.py`)
- Realtime ARI handler → Session manager: creates and updates (evidence: `src/voice_assistant/telephony/realtime_ari_handler.py`)
- Realtime ARI handler → External media: starts stream (evidence: `src/voice_assistant/telephony/realtime_ari_handler.py`)
- Realtime ARI handler → Gemini Live client: uses (evidence: `src/voice_assistant/telephony/realtime_ari_handler.py`)
- External media → Realtime audio processor: processes audio (evidence: `src/voice_assistant/telephony/external_media_handler.py`)
- External media → Gemini Live client: exchanges audio (evidence: `src/voice_assistant/telephony/external_media_handler.py`)
- External media → Session manager: tracks session (evidence: `src/voice_assistant/telephony/external_media_handler.py`)
- Gemini Live client → Google Gemini: streams conversation (evidence: `README.md`)
- Standalone user → Standalone assistant: speaks to (evidence: `README.md`)
- Standalone assistant → Gemini client: requests responses (evidence: `src/main.py`)
- Standalone assistant → Speech recognition: transcribes speech (evidence: `README.md`)
- Standalone assistant → Text to speech: speaks response (evidence: `README.md`)
- WebSocket Gemini client → Advanced audio processor: processes audio (evidence: `src/voice_assistant/ai/websocket_gemini_client.py`)
- WebSocket Gemini client → Function calling: dispatches calls (evidence: `src/voice_assistant/ai/websocket_gemini_client.py`)
- WebSocket Gemini client → Assistant prompts: uses (evidence: `src/voice_assistant/ai/websocket_gemini_client.py`)
- WebSocket Gemini client → Weather tool: registers tool (evidence: `src/voice_assistant/ai/websocket_gemini_client.py`)
- WebSocket Gemini client → RTP streaming: streams audio (evidence: `src/voice_assistant/ai/websocket_gemini_client.py`)
- Gemini Live client → Realtime audio processor: uses (evidence: `src/voice_assistant/ai/gemini_live_client.py`)
- Security manager → Authentication: authenticates (evidence: `src/voice_assistant/security/security_manager.py`)
- Security manager → Rate limiting: checks limits (evidence: `src/voice_assistant/security/security_manager.py`)
- Security manager → Input validation: validates input (evidence: `src/voice_assistant/security/security_manager.py`)
- Security manager → Audit logging: records events (evidence: `src/voice_assistant/security/security_manager.py`)
- Caller → Legacy ARI handler: uses legacy mode (evidence: `README.md`)
