# silvanojr/whatsapptranscription architecture

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

- Interactive diagram: https://gitdiagram.com/silvanojr/whatsapptranscription
- Repository: https://github.com/silvanojr/whatsapptranscription

## Overview

##### Main Components
- Configuration & Environment: Represent the .env file and environment variables (like OPENAI_API_KEY, GROUPS, PATH_MP3, PATH_SESSION, SECRET_WORD) which control behavior.
- WhatsApp Connector: Since the application uses WhatsApp’s QR-code based device linking (and syncing), indicate a component that handles connection to WhatsApp. This module is responsible for managing session state (with volumes for /session) and syncing contacts/messages.
- Audio Processing & Conversion: Indicate a module that leverages ffmpeg for converting audio files. This module is triggered when a message contains the secret word and processes the audio to a format that can be further handled.
- OpenAI API Interface: Represent the integration component that takes the processed audio (or its textual transcription) and sends it to OpenAI for whatever task (speech-to-text or further processing) is intended.
- Core Application Logic: The main Node.js application (index.js) that ties together the above components, listens for WhatsApp events, and coordinates actions based on incoming data.
- Containerization & Deployment: Represent Docker and Docker Compose as containerization technology, including the volumes for storing persistent data (/session and /mp3). Also indicate the CI/CD pipelines (GitHub Workflows and GitLab CI) which ensure quality and deployment.

##### Relationships and Interactions
- The startup flow begins with the configuration module reading environment variables (from .env) within the containerized runtime.
- The WhatsApp Connector component initializes and displays a QR code on the console to allow device linking. Once linked, it handles message/event streams.
- Upon receiving an audio message (or a message triggering audio processing via the configured SECRET_WORD), the message is passed to the Audio Processing module. This module calls the local ffmpeg installation to convert/process the audio files.
- The processed output is then forwarded to the OpenAI API Interface component which uses the provided OpenAI API key to send the audio/text data for further processing.
- The Core Application Logic is responsible for orchestration between receiving events from WhatsApp, managing audio processing, and integrating with OpenAI.
- All of these interactions occur within a Dockerized environment which also leverages persistent volumes (for session management and storing audio files).

##### Important Architectural Patterns or Design Principles
- Modular Design: Separating the application into distinct components (WhatsApp Connector, Audio Processor, OpenAI API Interface) makes the system easier to understand, extend, and maintain.
- Containerization: Use of Docker and volumes clearly separates deployment concerns and ensures environmental consistency.
- Environment-based Configuration: Externalizing configuration via the .env file simplifies deployment across various environments.
- Asynchronous Event Handling: The nature of message-based interactions, QR-code linking and asynchronous synchronization with WhatsApp indicate an event-driven, asynchronous architecture.

##### Detail and Clarity
- Every module has a clear, concise label.
- Notes on key integrated technologies (Node.js, Docker, ffmpeg, OpenAI API) and mention any dependency on external services (WhatsApp linking and API endpoints).
- Adding annotations to indicate the use of asynchronous handling and container orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Environment"
        CE["Configuration & Environment"]:::config
        WC["WhatsApp Connector"]:::whatsApp
        CA["Core Application Logic"]:::core
        AP["Audio Processing Module (ffmpeg)"]:::audio
        OA["OpenAI API Interface"]:::openai
    end

    WS["WhatsApp Servers"]:::external
    OI["OpenAI API"]:::external
    CD["Containerization & Deployment"]:::deploy

    %% Configuration flows
    CE -->|"configuration"| CA
    CE -->|"configuration"| WC
    CE -->|"configuration"| AP
    CE -->|"configuration"| OA

    %% WhatsApp connector interactions
    WS -->|"QR_linking_and_messages"| WC
    WC -->|"event_stream"| CA
    CA -->|"reply_message"| WC

    %% Audio processing and AI integration
    CA -->|"trigger_SECRET_WORD"| AP
    AP -->|"processed_audio"| OA
    OA -->|"API_call"| OI
    OI -->|"API_response"| OA
    OA -->|"result"| CA

    %% Deployment connection
    CD -->|"deployment"| CA

    %% Click Events
    click CE "https://github.com/silvanojr/whatsapptranscription/blob/main/.env"
    click WC "https://github.com/silvanojr/whatsapptranscription/blob/main/index.js"
    click CA "https://github.com/silvanojr/whatsapptranscription/blob/main/index.js"
    click AP "https://github.com/silvanojr/whatsapptranscription/blob/main/index.js"
    click OA "https://github.com/silvanojr/whatsapptranscription/blob/main/index.js"
    click CD "https://github.com/silvanojr/whatsapptranscription/tree/main/Dockerfile"
    click CD "https://github.com/silvanojr/whatsapptranscription/blob/main/.github/workflows/docker-image.yml"
    click CD "https://github.com/silvanojr/whatsapptranscription/blob/main/.gitlab-ci.yml"

    %% Styles
    classDef config fill:#9fe2bf, stroke:#333, stroke-width:2px;
    classDef whatsApp fill:#f7a278, stroke:#333, stroke-width:2px;
    classDef core fill:#fce883, stroke:#333, stroke-width:2px;
    classDef audio fill:#f9c74f, stroke:#333, stroke-width:2px;
    classDef openai fill:#90be6d, stroke:#333, stroke-width:2px;
    classDef deploy fill:#a0c4ff, stroke:#333, stroke-width:2px;
    classDef external fill:#eeeeee, stroke:#333, stroke-width:2px;
```
