# jayantakol/ai_voice_agent architecture

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

- Interactive diagram: https://gitdiagram.com/jayantakol/ai_voice_agent
- Repository: https://github.com/jayantakol/ai_voice_agent

## Overview

##### Project type and purpose
- This is a full-stack AI Voice Generation Agent.
- Frontend: React + Vite + TypeScript (single‐page app).
- Backend: FastAPI (Python 3.10+) exposing a REST API.
- Purpose: allow users to upload a voice sample, clone it via ElevenLabs, and generate multilingual, age/gender-styled TTS.

##### File structure
- Top-level separation:
- client/ (React UI)
- server/ (FastAPI API + services)
- client/src/ui/components: UI is organized into step-components (upload, language, controls, etc.)
- server/models/schemas.py: Pydantic models for request/response data.
- server/services: business logic lives in:
- elevenlabs_client.py (wraps ElevenLabs API calls)
- audio_postprocess.py (DSP adjustments: pitch, speed, clarity)
- server/main.py: FastAPI app, routes for upload, clone, generate, and static file serving.
- ENV_EXAMPLE.txt + requirements.txt: configuration & dependencies.

##### README for additional insights
- REST API endpoints:
- POST /api/voice/upload
- POST /api/voice/clone
- POST /api/voice/generate
- GET /api/audio/{filename}
- Workflow: Upload → Clone → Generate → Serve audio
- Privacy: sample deletion, temp storage, cleanup needed
- Tech stack explicitly called out (React, FastAPI, Python, Node, ElevenLabs).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side"
        direction TB
        User["User & Browser"]:::external
        ReactApp["React App"]:::frontend
        Entry["main.tsx"]:::frontend
        AppComp["App.tsx"]:::frontend
        subgraph "UI Components"
            direction TB
            UploadStep["UploadStep"]:::frontend
            LanguageStep["LanguageStep"]:::frontend
            VoiceTypeStep["VoiceTypeStep"]:::frontend
            TextStep["TextStep"]:::frontend
            ControlsStep["ControlsStep"]:::frontend
            GenerateStep["GenerateStep"]:::frontend
        end
        ConfigPackage["package.json"]:::frontend
        ConfigTS["tsconfig.json"]:::frontend
        ViteConfig["vite.config.ts"]:::frontend
    end

    %% Server Side
    subgraph "Server Side"
        direction TB
        APILayer["FastAPI App\n(main.py)"]:::backend
        Schemas["Schemas\n(schemas.py)"]:::backend
        subgraph "Services"
            direction TB
            ElevenClient["ElevenLabs Client"]:::service
            AudioPost["Audio Postprocess"]:::service
        end
        Storage["Temp File Storage"]:::storage
        ReqTxt["requirements.txt"]:::backend
        EnvExample["ENV_EXAMPLE.txt"]:::backend
    end

    %% External Service
    ElevenLabsAPI["ElevenLabs TTS API"]:::external

    %% Connections
    User -->|uses UI| ReactApp
    ReactApp -->|imports| Entry
    ReactApp -->|renders| AppComp
    AppComp -->|uses| UploadStep
    AppComp -->|uses| LanguageStep
    AppComp -->|uses| VoiceTypeStep
    AppComp -->|uses| TextStep
    AppComp -->|uses| ControlsStep
    AppComp -->|uses| GenerateStep
    ReactApp -->|"POST /api/voice/upload"| APILayer
    APILayer -->|uses| Schemas
    APILayer -->|"calls upload_sample"| ElevenClient
    ElevenClient -->|sends sample| ElevenLabsAPI
    ElevenLabsAPI -->|returns voice_id| ElevenClient
    APILayer -->|"calls generate_voice"| ElevenClient
    ElevenClient -->|returns raw audio| APILayer
    APILayer -->|calls postprocess| AudioPost
    AudioPost -->|processed audio| Storage
    APILayer -->|"GET /api/audio/{filename}"| Storage
    ReactApp -->|"GET /api/audio/{filename}"| Storage

    %% Click Events - Client
    click Entry "https://github.com/jayantakol/ai_voice_agent/blob/main/client/src/main.tsx"
    click AppComp "https://github.com/jayantakol/ai_voice_agent/blob/main/client/src/ui/App.tsx"
    click UploadStep "https://github.com/jayantakol/ai_voice_agent/blob/main/client/src/ui/components/UploadStep.tsx"
    click LanguageStep "https://github.com/jayantakol/ai_voice_agent/blob/main/client/src/ui/components/LanguageStep.tsx"
    click VoiceTypeStep "https://github.com/jayantakol/ai_voice_agent/blob/main/client/src/ui/components/VoiceTypeStep.tsx"
    click TextStep "https://github.com/jayantakol/ai_voice_agent/blob/main/client/src/ui/components/TextStep.tsx"
    click ControlsStep "https://github.com/jayantakol/ai_voice_agent/blob/main/client/src/ui/components/ControlsStep.tsx"
    click GenerateStep "https://github.com/jayantakol/ai_voice_agent/blob/main/client/src/ui/components/GenerateStep.tsx"
    click ConfigPackage "https://github.com/jayantakol/ai_voice_agent/blob/main/client/package.json"
    click ConfigTS "https://github.com/jayantakol/ai_voice_agent/blob/main/client/tsconfig.json"
    click ViteConfig "https://github.com/jayantakol/ai_voice_agent/blob/main/client/vite.config.ts"

    %% Click Events - Server
    click APILayer "https://github.com/jayantakol/ai_voice_agent/blob/main/server/main.py"
    click Schemas "https://github.com/jayantakol/ai_voice_agent/blob/main/server/models/schemas.py"
    click ElevenClient "https://github.com/jayantakol/ai_voice_agent/blob/main/server/services/elevenlabs_client.py"
    click AudioPost "https://github.com/jayantakol/ai_voice_agent/blob/main/server/services/audio_postprocess.py"
    click ReqTxt "https://github.com/jayantakol/ai_voice_agent/blob/main/server/requirements.txt"
    click EnvExample "https://github.com/jayantakol/ai_voice_agent/blob/main/server/ENV_EXAMPLE.txt"
    click README "https://github.com/jayantakol/ai_voice_agent/blob/main/README.md"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#00796B,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef service fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef storage fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,stroke-dasharray: 5 5
```
