# nerveband/whatsapp_voice_transcription architecture

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

- Interactive diagram: https://gitdiagram.com/nerveband/whatsapp_voice_transcription
- Repository: https://github.com/nerveband/whatsapp_voice_transcription

## Overview

##### Main Components

a. Client Layer:
- WhatsApp Client (using @whiskeysockets/baileys)
- QR Code Authentication Interface

b. Application Core:
- Voice Note Handler
- Transcription Service Manager
- Summary Generation Manager
- Message Response Handler

c. External Services:
- WhatsApp Web API
- OpenAI Services (Whisper API & GPT)
- Deepgram API
- Anthropic Claude API

**┌─────────────────────────────────────────────────────────────┐**
- Client Layer                            │
- ┘
- ↕
**┌─────────────────────────────────────────────────────────────┐**
- Application Core                         │
- ┘
- ↕
**┌─────────────────────────────────────────────────────────────┐**
- External Services                        │
- ┘

##### Key Flows to Highlight

a. Authentication Flow:
- QR Code Generation → WhatsApp Web Authentication → Session Storage

b. Voice Note Processing Flow:
- Voice Note Reception → Transcription Service Selection → Text Generation → Summary Creation → Response Delivery

##### Important Elements

a. Storage Components:
- .wwebjs_auth (Session storage)
- .wwebjs_cache (Cache storage)
- Environment Variables (.env)

b. Integration Points:
- WhatsApp Web API Connection
- AI Service API Endpoints
- Authentication Handlers

a. Modularity:
- Separate services for transcription (Whisper/Deepgram)
- Separate services for summarization (GPT/Claude)
- Independent authentication handling

b. Data Flow:
- Voice note input path
- Transcription processing path
- Summary generation path
- Response delivery path

##### Specific connections

**WhatsApp Client ↔ Session Manager ↔ Voice Note Handler**
- ↕
- Transcription Service Manager
- ↕
- Summary Generation Manager
- ↕
- Message Response Handler

##### Technical Details to Note

- Error handling paths
- Async operations
- Security boundaries
- Configuration points

##### Implementation Notes

- Version information for major components
- Scalability points
- Error handling mechanisms
- Configuration dependencies

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef client fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#f1c40f,stroke:#f39c12,color:black
    classDef storage fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef auth fill:#e74c3c,stroke:#c0392b,color:white
    
    %% Client Layer
    subgraph ClientLayer
        WA[WhatsApp Client]:::client
        QR[QR Code Authentication]:::auth
    end
    click WA "https://github.com/nerveband/whatsapp_voice_transcription/blob/master/whatsapp_voice_note_alert.js"

    %% Application Core
    subgraph AppCore
        VH[Voice Note Handler]:::core
        TSM[Transcription Service Manager]:::core
        SGM[Summary Generation Manager]:::core
        MRH[Message Response Handler]:::core
        SM[Session Manager]:::core
    end
    click VH "https://github.com/nerveband/whatsapp_voice_transcription/blob/master/speech_to_text.js"

    %% Storage Layer
    subgraph Storage
        SS[Session Storage]:::storage
        CS[Cache System]:::storage
        AS[Authentication Storage]:::storage
        LS[Local Storage]:::storage
        DB[Database Storage]:::storage
    end
    click SS "https://github.com/nerveband/whatsapp_voice_transcription/tree/master/.wwebjs_auth/session/"
    click CS "https://github.com/nerveband/whatsapp_voice_transcription/tree/master/.wwebjs_cache/"
    click AS "https://github.com/nerveband/whatsapp_voice_transcription/tree/master/.wwebjs_auth/session/Default/"
    click LS "https://github.com/nerveband/whatsapp_voice_transcription/tree/master/.wwebjs_auth/session/Default/Local Storage/"
    click DB "https://github.com/nerveband/whatsapp_voice_transcription/tree/master/.wwebjs_auth/session/Default/databases/"

    %% External Services
    subgraph ExternalServices
        WAPI[WhatsApp Web API]:::external
        Whisper[OpenAI Whisper API]:::external
        GPT[OpenAI GPT]:::external
        DG[Deepgram API]:::external
        Claude[Anthropic Claude API]:::external
    end

    %% Configuration
    Config[Configuration/.env]:::storage
    click Config "https://github.com/nerveband/whatsapp_voice_transcription/blob/master/.env.example"

    %% Connections
    WA --> QR
    QR --> SM
    SM --> SS
    WA --> VH
    VH --> TSM
    TSM --> |Transcription Request| Whisper
    TSM --> |Transcription Request| DG
    TSM --> SGM
    SGM --> |Summary Request| GPT
    SGM --> |Summary Request| Claude
    SGM --> MRH
    MRH --> WA
    
    %% Storage Connections
    SM --> CS
    SM --> AS
    SM --> LS
    SM --> DB
    
    %% API Connections
    WA <--> WAPI
    
    %% Configuration Connections
    Config --> TSM
    Config --> SGM
    Config --> SM

    %% Legend
    subgraph Legend
        C1[Client Components]:::client
        C2[Core Components]:::core
        C3[External Services]:::external
        C4[Storage Components]:::storage
        C5[Auth Components]:::auth
    end
```
