# huntingphi/voice-to-note architecture

> Architecture diagram of the GitHub repository huntingphi/voice-to-note, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huntingphi/voice-to-note
- Repository: https://github.com/huntingphi/voice-to-note

## Overview

##### Project Type and Purpose
- Type: A serverless/flask‐based WhatsApp bot that transcribes audio to text.
- Purpose: Receive voice notes via Twilio WhatsApp, fetch the audio from S3, run it through Google Cloud Speech-to-Text, and reply with the transcription.

##### Main Components
- User Device: WhatsApp client that sends/receives voice notes.
- Twilio WhatsApp Sandbox: Entry point for incoming messages and voice notes; handles webhooks and callbacks.
- S3 Bucket: Storage location for voice note media.
- API Endpoint (Flask on AWS Lambda):
- lambda_function.py handles incoming HTTP POSTs from Twilio.
- fetch_vn.py downloads the media file from S3 via Twilio’s provided URL.
- recognize_speech.py calls Google Cloud Speech-to-Text API and returns the transcript.
- Google Cloud Speech-to-Text API: External service for speech recognition.
- Twilio Messaging API: Sends the text response back to the user.

##### Relationships and Data Flow
1. User records voice note in WhatsApp → Twilio Sandbox receives it.
2. Twilio issues a webhook POST to /bot-receiver on your Flask/Lambda endpoint.
3. lambda_function.py parses the request and extracts the media URL.
4. fetch_vn.py downloads the audio file from S3 (using Twilio’s signed URL).
5. recognize_speech.py sends audio to Google Cloud STT → receives transcript.
6. lambda_function.py posts the transcript back to the user via Twilio’s API (HTTP POST).
7. (Optional) Twilio posts status updates to /bot-status for delivery callbacks.

##### Architectural Patterns and Design Principles
- Serverless / Function-as-a-Service: The Flask app runs in AWS Lambda.
- Webhook-Driven Flow: Twilio callbacks trigger your service.
- Single Responsibility Modules: Separate scripts for fetching media and speech recognition.
- Externalized Configuration: Environment variables for Google credentials and Twilio tokens.
- Stateless Request Handling: Each webhook invocation is independent.

##### Final Checklist
- Clear, descriptive component labels.
- Callout for environment/configuration (AWS Lambda env vars).
- A concise note on “No persistent state” to indicate stateless design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Entry
    U["WhatsApp User"]:::user
    TS["Twilio WhatsApp Sandbox"]:::external

    %% Compute Layer
    subgraph "Compute - AWS Lambda (Flask App)" 
        style Compute fill:#FFE5B4,stroke:#E69A00
        LF["lambda_function.py\n(Webhook Handler)"]:::compute
        FV["fetch_vn.py\n(Media Fetch Module)"]:::compute
        RS["recognize_speech.py\n(Speech Recognition)"]:::compute
        RM["requirements.txt"]:::config
        RD["README.md"]:::doc
        LC["LICENSE"]:::doc
        NoteEnv{{"Env Vars:\nGOOGLE_APPLICATION_CREDENTIALS\nTWILIO_AUTH_TOKEN"}}:::note
    end

    %% Storage and External Services
    S3["S3 Bucket"]:::storage
    GC["Google Cloud Speech-to-Text"]:::external
    TM["Twilio Messaging API"]:::external

    %% Data Flow
    U -->|"Send voice note"| TS
    TS -->|"Webhook POST /bot-receiver"| LF
    LF -->|"Extract media URL"| FV
    FV -->|"GET media via S3 URL"| S3
    FV -->|"Return audio file"| LF
    LF -->|"Invoke recognition"| RS
    RS -->|"gRPC/HTTPS"| GC
    GC -->|"Transcript"| RS
    RS -->|"Return transcript"| LF
    LF -->|"POST message"| TM
    TM -->|"Deliver transcript"| U

    %% Optional Status Callback
    TS -->|"Webhook POST /bot-status"| LF

    %% Click events
    click LF "https://github.com/huntingphi/voice-to-note/blob/master/lambda_function.py"
    click FV "https://github.com/huntingphi/voice-to-note/blob/master/fetch_vn.py"
    click RS "https://github.com/huntingphi/voice-to-note/blob/master/recognize_speech.py"
    click RM "https://github.com/huntingphi/voice-to-note/blob/master/requirements.txt"
    click RD "https://github.com/huntingphi/voice-to-note/blob/master/README.md"
    click LC "https://github.com/huntingphi/voice-to-note/tree/master/LICENSE"

    %% Styles
    classDef user fill:#CCFFFF,stroke:#0099CC,stroke-width:2px
    classDef external fill:#CCE5FF,stroke:#0059B3,stroke-width:2px
    classDef compute fill:#FFE5B4,stroke:#E69A00,stroke-width:2px
    classDef storage fill:#C6F6C6,stroke:#2E8B57,stroke-width:2px
    classDef doc fill:#F0E68C,stroke:#DAA520,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#FFF2CC,stroke:#D6A700,stroke-width:1px,stroke-dasharray: 5 5
    classDef note fill:#FFFFFF,stroke:#000000,stroke-dasharray: 2 2,stroke-width:1px
```
