# yugesh-003/whatsapp-news-sender architecture

> Architecture diagram of the GitHub repository yugesh-003/whatsapp-news-sender, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yugesh-003/whatsapp-news-sender
- Repository: https://github.com/yugesh-003/whatsapp-news-sender

## Overview

##### Project Type and Purpose
- This is an open-source, command-line Python application that:
- Fetches news articles from News API
- Converts text to speech via AWS Polly
- Sends the resulting audio via WhatsApp using Twilio (with SMS/MMS fallback)
- The single-script structure (news_to_audio.py) and minimal file tree indicate it follows a simple pipeline pattern with external service integrations.

A. Configuration Module
- Reads environment variables from `.env` (API keys, AWS credentials, Twilio credentials).
- Handles CLI arguments (`--category`, `--country`, `--count`, `--create-env`).
B. News Fetcher
- Invokes News API REST endpoint.
- Parses JSON response into a list of articles.
C. Text-to-Speech Converter
- Sends article text to AWS Polly.
- Receives and stores audio file(s) in the `output/` directory.
D. Messaging Sender
- Primary: Twilio WhatsApp API
- Fallback: Twilio SMS/MMS API
- Attaches or uploads the generated audio file.
E. Persistence
- Local file storage for audio (`output` folder)
- (Implicit) Temporary in-memory structures for article metadata.

##### Relationships & Data Flow
- Start → Configuration
- Load credentials & parse CLI arguments
- Configuration → News Fetcher
- Pass in category, country, count
- News Fetcher → Text-to-Speech Converter
- For each article text
- Text-to-Speech Converter → Persistence
- Write out `.mp3` or `.ogg` files
- Persistence → Messaging Sender
- Retrieve file paths, feed into Twilio APIs
- Messaging Sender → External Services
- WhatsApp channel → if success: DONE
- else → SMS/MMS channel
- End

##### Architectural Patterns & Principles
- Pipeline Pattern: data flows through distinct stages (fetch → transform → deliver)
- Single Responsibility: each logical component has a focused role
- External Integration Points: clearly separate wrappers for News API, AWS Polly, Twilio
- Fail-fast and Fallback: WhatsApp primary, SMS/MMS fallback

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pipeline stages
    subgraph "Pipeline"
        direction TB
        Config["Configuration Module\n(load .env, parse CLI)"]:::code
        Fetcher["News Fetcher\n(GET /v2/top-headlines)"]:::code
        Converter["Text-to-Speech Converter\n(SynthesizeSpeech)"]:::code
        Storage["Persistence\n(local audio files)"]:::storage
        Sender["Messaging Sender\n(WhatsApp primary, SMS/MMS fallback)"]:::code
    end

    %% External services
    NewsAPI["News API"]:::external
    Polly["AWS Polly"]:::external
    Twilio["Twilio API\n(WhatsApp/SMS/MMS)"]:::external

    %% Documentation & Dependencies
    README["README.md\n(Documentation)"]:::docs
    Requirements["requirements.txt\n(Dependencies)"]:::docs

    %% Data Flow
    Config -->|"category, country, count"| Fetcher
    Fetcher -->|"GET /v2/top-headlines"| NewsAPI
    NewsAPI -->|"JSON articles"| Fetcher
    Fetcher -->|"article text"| Converter
    Converter -->|"SynthesizeSpeech"| Polly
    Polly -->|"audio binary"| Converter
    Converter -->|"write .mp3/.ogg"| Storage
    Storage -->|"file paths"| Sender
    Sender -->|"SendWhatsAppMessage"| Twilio
    Twilio -->|success| Done["Done"]
    Twilio -->|failure| SenderSMS["Retry via SMS/MMS"]:::code
    SenderSMS -->|"SendSMS/MMS"| Twilio
    Twilio -->|sms confirmation| Done

    %% Attach docs
    README -.-> Config
    Requirements -.-> Config

    %% Click Events
    click Config "https://github.com/yugesh-003/whatsapp-news-sender/blob/master/news_to_audio.py"
    click Fetcher "https://github.com/yugesh-003/whatsapp-news-sender/blob/master/news_to_audio.py"
    click Converter "https://github.com/yugesh-003/whatsapp-news-sender/blob/master/news_to_audio.py"
    click Sender "https://github.com/yugesh-003/whatsapp-news-sender/blob/master/news_to_audio.py"
    click Storage "https://github.com/yugesh-003/whatsapp-news-sender/tree/master/output/"
    click README "https://github.com/yugesh-003/whatsapp-news-sender/blob/master/README.md"
    click Requirements "https://github.com/yugesh-003/whatsapp-news-sender/blob/master/requirements.txt"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef external fill:#D5F5E3,stroke:#28a745,color:#28a745,stroke-width:1px;
    classDef storage fill:#E8E8E8,stroke:#6c757d,color:#6c757d,stroke-width:1px;
    classDef docs fill:#FEF5E7,stroke:#d39e00,color:#d39e00,stroke-width:1px;
```
