# mahammadwahab540/callagent architecture

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

- Interactive diagram: https://gitdiagram.com/mahammadwahab540/callagent
- Repository: https://github.com/mahammadwahab540/callagent

## Overview

##### Project type and purpose
- This is a single-page front-end application built with React, TypeScript, and Vite.

##### Main architectural components
a. User & Browser
- User’s microphone and speaker (via Web Audio)
- Host environment: Chrome/Firefox, running index.html + bundle from Vite.
b. React Application
- Entry: index.tsx → App.tsx
- Components folder:
– Stepper (controls stage flow)
– StageContent (per-stage UI layout)
– TranscriptDisplay (shows live transcripts)
– VoiceVisualizer (audio waveform/levels)
- Hooks: useVoiceAgent (manages voice-agent lifecycle & API calls)
- Utils: audioUtils (wrapper around Web Audio API for mic access, stream manipulation)
c. External Voice Service
- Could be OpenAI, Azure Speech-to-Text/Text-to-Speech, or a custom REST/WebSocket API
- Endpoint(s): stream audio in, receive text, send back audio responses
d. Configuration / Assets
- metadata.json (app metadata)
- constants.ts & types.ts (shared type definitions)
- Vite config & package.json (build/deploy settings)

##### Determining relationships & data flows
- The browser’s Web Audio API captures raw PCM from the microphone → passes it to audioUtils.
- audioUtils buffers/encodes audio → forwards to useVoiceAgent.
- useVoiceAgent opens WebSocket/REST calls to the external voice service.
- On transcript events, useVoiceAgent emits text → TranscriptDisplay subscribes & renders.
- On audio events (playback), useVoiceAgent provides audio buffers → VoiceVisualizer animates, and the browser audio output plays.
- Stepper & StageContent drive when recording starts/stops and which prompts appear.

##### Architectural patterns & principles
- Layered Architecture:
1. Presentation layer (React components)
2. Application logic layer (custom hooks, state management)
3. Infrastructure layer (audioUtils, external API)
- Single Responsibility: each React component & hook does one well-defined job.
- Dependency Inversion: components depend on abstracted hooks, not directly on low-level audio APIs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Browser Layer
    subgraph "User & Browser"
        Browser["Browser (Chrome/Firefox)"]:::device
        Mic["Microphone & Speaker"]:::device
        Html["index.html"]:::device
    end

    Browser -->|loads| Html
    Browser -->|captures raw PCM| audioUtils

    %% React Application Layer
    subgraph "React Application"
        index["index.tsx"]:::entry
        app["App.tsx"]:::entry

        subgraph "Components"
            Stepper["Stepper"]:::ui
            StageContent["StageContent"]:::ui
            TranscriptDisplay["TranscriptDisplay"]:::ui
            VoiceVisualizer["VoiceVisualizer"]:::ui
            Icons["Icons"]:::ui
        end

        subgraph "Hooks"
            VoiceAgent["useVoiceAgent Hook"]:::logic
        end

        subgraph "Utils"
            audioUtils["audioUtils"]:::infra
        end

        constants["constants.ts"]:::config
        types["types.ts"]:::config
        metadata["metadata.json"]:::config
        viteConfig["vite.config.ts"]:::config
        pkg["package.json"]:::config
    end

    Html -->|mounts App| index
    index -->|renders| app
    app -->|renders| Stepper
    app -->|renders| StageContent
    app -->|renders| TranscriptDisplay
    app -->|renders| VoiceVisualizer
    app -->|renders| Icons
    app -->|uses| VoiceAgent

    Mic -->|raw PCM| audioUtils
    audioUtils -->|buffers/encodes| VoiceAgent

    VoiceAgent -->|WebSocket/REST| ExternalService
    VoiceAgent -->|JSON transcript| TranscriptDisplay
    VoiceAgent -->|audio buffer| VoiceVisualizer
    VoiceAgent -->|controls| Stepper
    VoiceAgent -->|controls| StageContent

    %% External Service Layer
    subgraph "External Voice Service"
        ExternalService["External Voice Service API"]:::external
    end

    %% Click Events
    click index "https://github.com/mahammadwahab540/callagent/blob/main/index.tsx"
    click app "https://github.com/mahammadwahab540/callagent/blob/main/App.tsx"
    click Stepper "https://github.com/mahammadwahab540/callagent/blob/main/components/Stepper.tsx"
    click StageContent "https://github.com/mahammadwahab540/callagent/blob/main/components/StageContent.tsx"
    click TranscriptDisplay "https://github.com/mahammadwahab540/callagent/blob/main/components/TranscriptDisplay.tsx"
    click VoiceVisualizer "https://github.com/mahammadwahab540/callagent/blob/main/components/VoiceVisualizer.tsx"
    click Icons "https://github.com/mahammadwahab540/callagent/blob/main/components/Icons.tsx"
    click VoiceAgent "https://github.com/mahammadwahab540/callagent/blob/main/hooks/useVoiceAgent.ts"
    click audioUtils "https://github.com/mahammadwahab540/callagent/blob/main/utils/audioUtils.ts"
    click constants "https://github.com/mahammadwahab540/callagent/blob/main/constants.ts"
    click types "https://github.com/mahammadwahab540/callagent/blob/main/types.ts"
    click metadata "https://github.com/mahammadwahab540/callagent/blob/main/metadata.json"
    click viteConfig "https://github.com/mahammadwahab540/callagent/blob/main/vite.config.ts"
    click pkg "https://github.com/mahammadwahab540/callagent/blob/main/package.json"
    click Html "https://github.com/mahammadwahab540/callagent/blob/main/index.html"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef logic fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef infra fill:#E0FFE0,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef device fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef entry fill:#C8F7FF,stroke:#333,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#333,stroke-width:1px

    class Stepper,StageContent,TranscriptDisplay,VoiceVisualizer,Icons ui
    class VoiceAgent logic
    class audioUtils infra
    class ExternalService external
    class Browser,Mic,Html device
    class index,app entry
    class constants,types,metadata,viteConfig,pkg config
```
