# satvik-gautam/ai-agentic-doctor architecture

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

- Interactive diagram: https://gitdiagram.com/satvik-gautam/ai-agentic-doctor
- Repository: https://github.com/satvik-gautam/ai-agentic-doctor

## Overview

##### Project Type and Purpose
- This is a modular, single‐page, full‐stack AI application built in Python with a web UI (Gradio) that simulates a virtual doctor consultation.
- It integrates speech‐to‐text, image analysis, and text‐to‐speech to process patient inputs and return medical insights.

##### High‐Level Components
A. Presentation Layer (Gradio UI)
- app.py: Defines the web interface, custom CSS, input widgets (microphone, file upload), and result panels.
B. Audio Ingestion & Transcription
- voice_of_the_patient.py: Captures microphone audio (SpeechRecognition + Pydub + PortAudio), saves MP3, calls Groq Whisper API for transcription.
C. Image Preprocessing & AI Core
- brain_of_doctor.py: Base64‐encodes uploaded images; invokes Groq Llama model with a system prompt combining text + optional image.
D. Response Synthesis & Playback
- voice_of_the_doctor.py: Takes AI’s text response, uses gTTS to generate MP3 (optionally ElevenLabs), returns audio file.
E. Configuration & Hosting
- .env + python-dotenv: Stores API keys for Groq and TTS services.
- .gradio/: Certificates and temporary hosted‐app files (Hugging Face Spaces integration).
F. External Services
- gTTS (Google Text‐to‐Speech)
- (Optional) ElevenLabs TTS
- Hugging Face Spaces (deployment environment)

##### Data Flow & Relationships
1) User clicks microphone → app.py routes to voice_of_the_patient.py → raw audio → Groq Whisper → transcription text → back to app.py
2) User uploads image (optional) → app.py hands file to brain_of_doctor.py → base64 encoding
3) app.py calls brain_of_doctor.py with text + image → Groq Llama → AI’s medical evaluation (text)
4) app.py sends AI text to voice_of_the_doctor.py → gTTS → MP3
5) app.py updates Gradio UI with: (a) transcription text, (b) AI’s text response, (c) auto-playing MP3.

##### Architectural Patterns & Principles
- Layered/Onion Architecture: Presentation → Orchestration (app.py) → Domain modules → External APIs.
- Separation of Concerns: Distinct modules for audio I/O, image handling, AI logic, and TTS.
- Modular & Extensible: Easy to switch TTS engines, add preprocessing steps, or change AI models.
- Environment‐Driven Configuration: All keys and endpoints in .env.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Gradio UI\napp.py"]:::internal
    end

    %% Orchestration & Modules
    subgraph "Backend Modules"
        VoiceIngest["Audio Ingestion & Transcription\nvoice_of_the_patient.py"]:::internal
        ImageAI["Image Preprocessing & AI Core\nbrain_of_doctor.py"]:::internal
        ResponseSynthesis["Response Synthesis & Playback\nvoice_of_the_doctor.py"]:::internal
    end

    %% Configuration & Hosting
    subgraph "Config & Hosting"
        Env["Environment Config\n.env"]:::config
        Config["Dependency Config\nrequirements.txt"]:::config
        Hosting["Hosting & Temp Files\n.gradio/"]:::config
    end

    %% Documentation
    subgraph "Docs & License"
        License["LICENSE"]:::doc
        Readme["README.md"]:::doc
    end

    %% External Services
    subgraph "AI Core Services"
        GroqWhisper[(Groq Whisper API)]:::external
        GroqLlama[(Groq Llama API)]:::external
    end
    gTTS[(gTTS/ElevenLabs TTS)]:::external
    HFSpaces[(Hugging Face Spaces)]:::external

    %% Data Flows
    UI -->|"1. record audio"| VoiceIngest
    VoiceIngest -->|"transcription request"| GroqWhisper
    GroqWhisper -->|"transcription text"| UI

    UI -->|"2. upload image"| ImageAI
    ImageAI -->|"3. AI request"| GroqLlama
    GroqLlama -->|"AI text response"| UI

    UI -->|"4. send text"| ResponseSynthesis
    ResponseSynthesis -->|"generate audio"| gTTS
    gTTS -->|"audio file"| UI

    %% Hosting
    UI --> HFSpaces
    Hosting --> HFSpaces

    %% Config & Docs relations
    Env --- UI
    Config --- UI
    License --- UI
    Readme --- UI

    %% Click Events
    click UI "https://github.com/satvik-gautam/ai-agentic-doctor/blob/master/app.py"
    click VoiceIngest "https://github.com/satvik-gautam/ai-agentic-doctor/blob/master/voice_of_the_patient.py"
    click ImageAI "https://github.com/satvik-gautam/ai-agentic-doctor/blob/master/brain_of_doctor.py"
    click ResponseSynthesis "https://github.com/satvik-gautam/ai-agentic-doctor/blob/master/voice_of_the_doctor.py"
    click Config "https://github.com/satvik-gautam/ai-agentic-doctor/blob/master/requirements.txt"
    click Hosting "https://github.com/satvik-gautam/ai-agentic-doctor/tree/master/.gradio/"
    click License "https://github.com/satvik-gautam/ai-agentic-doctor/tree/master/LICENSE"
    click Readme "https://github.com/satvik-gautam/ai-agentic-doctor/blob/master/README.md"

    %% Styles
    classDef internal fill:#B3D4FC,stroke:#2F75B5,color:#000;
    classDef external fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef config fill:#FFE0B2,stroke:#F57C00,color:#000;
    classDef doc fill:#E0E0E0,stroke:#757575,color:#000;
```
