# aarnhub/python-sms-sender architecture

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

- Interactive diagram: https://gitdiagram.com/aarnhub/python-sms-sender
- Repository: https://github.com/aarnhub/python-sms-sender

## Overview

##### Project Type and Purpose
- This is a small, command-line Python tool for bulk SMS sending via an external SMS Gateway API (Proovl).
- Users interact with it in a terminal; it stores API credentials locally and issues HTTP requests to send messages.

##### File Structure Analysis
- Top-level files:
- README.md – describes usage, API setup, storage behavior.
- sms-sender.py – likely the main entry point (handles CLI arguments, reads credentials, invokes send logic).
- smser.py – encapsulates the SMS-sending logic (API client, formatting requests, error handling).
- Upon first run and API setup, it creates a local pickle file (`smssenderdb.pickle`) to persist credentials.

##### Key Components
a. CLI Layer (sms-sender.py)
- Parses command-line arguments (single vs. bulk, message text, recipient list).
- Loads/stores configuration via smser module.
b. Configuration Store
- The pickled file acting as a local datastore for API key, user ID, token.
c. SMS Module (smser.py)
- Contains classes/functions to:
- Read/update credentials in the pickle DB.
- Build HTTP requests.
- Handle responses, errors, retries.
d. External SMS Gateway (Proovl API)
- A REST-ful HTTP endpoint that actually dispatches the messages to mobile networks.
e. (Optional) Logging/Error Handling
- Any console logs or error streams produced by the scripts.

##### Relationships and Data Flow
- User invokes `sms-sender.py` → CLI Layer reads command.
- CLI Layer calls SMS Module → SMS Module loads credentials from pickle.
- SMS Module constructs HTTP request → sends to Proovl API over the Internet.
- Proovl responds → SMS Module interprets status → returns result to CLI.
- CLI Layer prints success or error messages to the user.

##### Architectural Patterns & Design Principles
- Separation of concerns: CLI parsing separated from API client logic.
- Single responsibility: `sms-sender.py` handles user interface; `smser.py` handles communication and storage.
- Extensibility point: adding new gateway integrations by extending `smser.py` or adding new modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI Application\n(sms-sender.py)"]:::code
    SMS["SMS Module\n(smser.py)"]:::code
    CONFIG["Configuration Store\n(smssenderdb.pickle)"]:::storage
    API["External SMS Gateway\n(Proovl API)"]:::external

    CLI -->|"args"| SMS
    SMS -->|"pickle.load/pickle.dump"| CONFIG
    CONFIG -->|"credentials"| SMS
    SMS -->|"HTTP JSON request"| API
    API -->|"HTTP JSON response"| SMS
    SMS -->|"status return"| CLI

    click CLI "https://github.com/aarnhub/python-sms-sender/blob/master/sms-sender.py"
    click SMS "https://github.com/aarnhub/python-sms-sender/blob/master/smser.py"
    click CONFIG "https://github.com/aarnhub/python-sms-sender/blob/master/smssenderdb.pickle"

    classDef code fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef storage fill:#ffffcc,stroke:#333,stroke-width:1px
    classDef external fill:#ccf2ff,stroke:#333,stroke-width:1px
```
