# gutierrezrileyg/sms-notification-system architecture

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

- Interactive diagram: https://gitdiagram.com/gutierrezrileyg/sms-notification-system
- Repository: https://github.com/gutierrezrileyg/sms-notification-system

## Overview

This repository is a collection of SMS-notification implementations and experiments, not one unified application. The clearest documented-by-code workflow is the Main Files continuous notifier: it fetches resident and GPS-status records, groups them by barangay, formats recipient numbers, dispatches SMS through a Node module, and can sync statuses to a Google Sheet. Other folders contain alternate spreadsheet/database and webhook-based status-writing implementations. Relationships for those unsampled variants are omitted; the README itself describes no further product capabilities.

Main entry points: [`Main Files/run_pipeline.py`](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/run_pipeline.py) (Continuous notifier), [`Fully Working_Notif System/run_pipeline.py`](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/run_pipeline.py) (Barangay SMS pipeline), [`Working_UniSMS API/run_pipeline.py`](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Working_UniSMS%20API/run_pipeline.py) (UniSMS pipeline), [`Main Files/data_retrieve.py`](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/data_retrieve.py) (Web app fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Notification orchestration"]
  node_pipeline["Continuous notifier<br/>[run_pipeline.py]"]
  node_full_pipeline["Barangay SMS pipeline<br/>[run_pipeline.py]"]
  node_unisms_pipeline["UniSMS pipeline<br/>[run_pipeline.py]"]
end

subgraph group_recipient_data["Recipient data"]
  node_webapp_fetch["Web app fetcher<br/>[data_retrieve.py]"]
  node_phone_format["Phone formatter<br/>[data_retrieve.py]"]
  node_excel_residents["Excel resident loader<br/>[data_retrieve.py]"]
  node_resident_db[("Resident database<br/>[data_retrieve.py]")]
  node_unisms_data["Spreadsheet data tools<br/>[data_retrieve.py]"]
end

subgraph group_delivery["SMS delivery"]
  node_sms_sender["SMS sender<br/>[sms_sending.js]"]
end

subgraph group_status["Status tracking"]
  node_sheet_status["Sheet status sync<br/>[sms_status.py]"]
  node_excel_status["Excel status writer<br/>[data_retrieve.py]"]
  node_unisms_status["Webhook status writer"]
end

node_operator(("Operator"))
node_web_app[("Web app data")]
node_sms_gateway["SMS gateway"]
node_google_sheets[("Google Sheets")]
node_status_workbook[("Status workbook")]
node_webhook_service["SMS provider webhook"]

node_operator -->|"starts"| node_pipeline
node_pipeline -->|"fetches records"| node_webapp_fetch
node_webapp_fetch -->|"requests data"| node_web_app
node_pipeline -->|"formats numbers"| node_phone_format
node_pipeline -->|"dispatches SMS"| node_sms_sender
node_sms_sender -.->|"sends SMS"| node_sms_gateway
node_pipeline -->|"updates status"| node_sheet_status
node_sheet_status -->|"posts updates"| node_google_sheets
node_operator -->|"starts"| node_full_pipeline
node_full_pipeline -->|"loads profiles"| node_excel_residents
node_excel_residents -->|"stores profiles"| node_resident_db
node_full_pipeline -->|"queries residents"| node_resident_db
node_full_pipeline -->|"sends SMS"| node_sms_gateway
node_full_pipeline -.->|"updates statuses"| node_excel_status
node_operator -->|"starts"| node_unisms_pipeline
node_unisms_pipeline -->|"loads profiles"| node_unisms_data
node_unisms_pipeline -->|"sends SMS"| node_sms_gateway
node_webhook_service -->|"posts status"| node_unisms_status
node_unisms_status -->|"writes statuses"| node_status_workbook

click node_pipeline "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/run_pipeline.py"
click node_webapp_fetch "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/data_retrieve.py"
click node_phone_format "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/data_retrieve.py"
click node_sms_sender "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/sms_sending.js"
click node_sheet_status "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/sms_status.py"
click node_excel_residents "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/data_retrieve.py"
click node_resident_db "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/data_retrieve.py"
click node_excel_status "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/data_retrieve.py"
click node_full_pipeline "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/run_pipeline.py"
click node_unisms_pipeline "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Working_UniSMS%20API/run_pipeline.py"
click node_unisms_data "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Working_UniSMS%20API/data_retrieve.py"
click node_unisms_status "https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Testing/PhilSMS/sms_status_writer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pipeline,node_full_pipeline,node_unisms_pipeline toneBlue
class node_webapp_fetch,node_phone_format,node_excel_residents,node_resident_db,node_unisms_data,node_web_app,node_google_sheets,node_status_workbook toneAmber
class node_sms_sender,node_webhook_service toneMint
class node_sheet_status,node_excel_status,node_unisms_status toneRose
class node_operator,node_sms_gateway toneIndigo
```

## Components

### Notification orchestration

- [Continuous notifier](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/run_pipeline.py): `Main Files/run_pipeline.py`
- [Barangay SMS pipeline](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/run_pipeline.py): `Fully Working_Notif System/run_pipeline.py`
- [UniSMS pipeline](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Working_UniSMS%20API/run_pipeline.py): `Working_UniSMS API/run_pipeline.py`

### Recipient data

- [Web app fetcher](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/data_retrieve.py): `Main Files/data_retrieve.py`
- [Phone formatter](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/data_retrieve.py): `Main Files/data_retrieve.py`
- [Excel resident loader](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/data_retrieve.py): `Fully Working_Notif System/data_retrieve.py`
- [Resident database](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/data_retrieve.py): `Fully Working_Notif System/data_retrieve.py`
- [Spreadsheet data tools](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Working_UniSMS%20API/data_retrieve.py): `Working_UniSMS API/data_retrieve.py`

### SMS delivery

- [SMS sender](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/sms_sending.js): `Main Files/sms_sending.js`

### Status tracking

- [Sheet status sync](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Main%20Files/sms_status.py): `Main Files/sms_status.py`
- [Excel status writer](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Fully%20Working_Notif%20System/data_retrieve.py): `Fully Working_Notif System/data_retrieve.py`
- [Webhook status writer](https://github.com/gutierrezrileyg/sms-notification-system/blob/main/Testing/PhilSMS/sms_status_writer.py): `Testing/PhilSMS/sms_status_writer.py`

### Other components

- **Operator**
- **Web app data**
- **SMS gateway**
- **Google Sheets**
- **Status workbook**
- **SMS provider webhook**

## Connections

- Operator → Continuous notifier: starts (evidence: `Main Files/run_pipeline.py`)
- Continuous notifier → Web app fetcher: fetches records (evidence: `Main Files/run_pipeline.py`)
- Web app fetcher → Web app data: requests data (evidence: `Main Files/data_retrieve.py`)
- Continuous notifier → Phone formatter: formats numbers (evidence: `Main Files/run_pipeline.py`)
- Continuous notifier → SMS sender: dispatches SMS (evidence: `Main Files/run_pipeline.py`)
- SMS sender → SMS gateway: sends SMS
- Continuous notifier → Sheet status sync: updates status (evidence: `Main Files/run_pipeline.py`)
- Sheet status sync → Google Sheets: posts updates (evidence: `Main Files/sms_status.py`)
- Operator → Barangay SMS pipeline: starts (evidence: `Fully Working_Notif System/run_pipeline.py`)
- Barangay SMS pipeline → Excel resident loader: loads profiles (evidence: `Fully Working_Notif System/run_pipeline.py`)
- Excel resident loader → Resident database: stores profiles (evidence: `Fully Working_Notif System/data_retrieve.py`)
- Barangay SMS pipeline → Resident database: queries residents (evidence: `Fully Working_Notif System/run_pipeline.py`)
- Barangay SMS pipeline → SMS gateway: sends SMS (evidence: `Fully Working_Notif System/run_pipeline.py`)
- Barangay SMS pipeline → Excel status writer: updates statuses
- Operator → UniSMS pipeline: starts (evidence: `Working_UniSMS API/run_pipeline.py`)
- UniSMS pipeline → Spreadsheet data tools: loads profiles (evidence: `Working_UniSMS API/run_pipeline.py`)
- UniSMS pipeline → SMS gateway: sends SMS (evidence: `Working_UniSMS API/run_pipeline.py`)
- SMS provider webhook → Webhook status writer: posts status (evidence: `Testing/PhilSMS/sms_status_writer.py`)
- Webhook status writer → Status workbook: writes statuses (evidence: `Testing/PhilSMS/sms_status_writer.py`)
