# elmadkouryassine/sms_gateway architecture

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

- Interactive diagram: https://gitdiagram.com/elmadkouryassine/sms_gateway
- Repository: https://github.com/elmadkouryassine/sms_gateway

## Overview

##### Project type and purpose
- This is a full-stack, Flask-based SMS gateway application with both a web UI and a REST API.
- It handles sending/receiving SMS and USSD via Arduino-connected SIM800L modules, persists data in MySQL, and runs a background scheduler daemon.

##### File structure
- Top level
- app.py – Flask app creation, blueprint registration, secret key, app.run()
- config.py – DB URI and other config
- run_scheduler.py – standalone scheduler loop
- database/
- models.py – SQLAlchemy ORM classes for users, roles, messages, tasks, SIM ports, etc.
- routes/ (Flask Blueprints)
- auth, admin, dashboard, inbox, reports, settings, sim_status, sms, sms_campaign, tasks, ussd, at (AT commands)
- auth_decorator for role-based access
- services/ (business logic)
- scheduler.py – poll pending tasks, update status
- serial_handler.py – low-level AT & USSD comms over /dev/ttyUSB*
- sim_monitor.py – fetch and log SIM health metrics
- sms_parser.py – parse CSV for bulk campaigns
- scripts/
- seed_*.py – DB seeding for roles, admin, demo, settings
- test_db.py, test_sim_updates.py
- static/ & templates/
- JS/CSS assets driving client behavior
- Jinja2 templates structured by feature and partials

##### Insights from the README
- Describes features: user/role management, single & bulk SMS, inbox, reports, USSD, AT console, real-time SIM status, REST endpoint.
- Emphasizes scheduler as a background daemon.
- Technology stack: Python 3.6+, Flask, Flask-SQLAlchemy, MySQL/MariaDB, Jinja2, serial comms.

a. Main components
1. Client Tier
– Web Browser (UI assets served by Flask)
– External systems (POST to /sms/api/send_single)
2. Web Application (Flask)
– Blueprints (auth, admin, sms, inbox, ussd, at, sim_status, dashboard, reports, settings)
– Static file server & template renderer
– REST API endpoint
3. Services Layer
– Scheduler Service (polls DB for pending SMS/USSD tasks)
– Serial Handler (AT & USSD over serial ports)
– SIM Monitor (periodically reads signal strength, operator)
– SMS Parser (bulk CSV import)
4. Database
– MySQL/MariaDB via SQLAlchemy models
5. Hardware
– Arduino Mega with multiple SIM800L modules on /dev/ttyUSB*

b. Relationships & data flow
- User/browser → HTTP → Flask routes → services & DB → HTML/JSON responses
- External alert system → REST API → Flask → services enqueues task → DB
- Scheduler → DB (get pending tasks) → Serial Handler → SIM modules → status back to DB
- SIM Monitor → Serial Handler → SIM modules → DB updates
- SMS Parser → reads CSV → DB inserts campaign tasks

c. Architectural patterns & principles
- Layered architecture: Presentation (templates/static), Application (Flask routes), Business Logic (services), Data Access (SQLAlchemy models).
- Background worker pattern for scheduler.
- Blueprint modularization for route separation.
- Dependency injection via config and app context.

d. Key technologies & libraries
- Flask + Flask-SQLAlchemy + Jinja2
- Python services using PySerial (serial_handler), scheduled via custom loop (run_scheduler.py)
- MySQL/MariaDB with pymysql driver
- Front-end: vanilla JS modules, CSS

##### Details
- Interaction with scripts only if they run in production (seed scripts are out-of-band).
- How configuration (config.py) feeds into all Python components.
- Serial port mapping (e.g., /dev/ttyUSB1 → SIM Port 2).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["Web Browser"]:::presentation
        External["External System"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        FlaskApp["Flask Web Server"]:::application
        Config["Configuration (config.py)"]:::application
        subgraph "Blueprints"
            direction TB
            Auth["Auth Blueprint"]:::application
            Admin["Admin Blueprint"]:::application
            Dashboard["Dashboard Blueprint"]:::application
            Inbox["Inbox Blueprint"]:::application
            Reports["Reports Blueprint"]:::application
            Settings["Settings Blueprint"]:::application
            SIMStatus["SIM Status Blueprint"]:::application
            SMS["SMS Blueprint"]:::application
            SMSCampaign["SMS Campaign Blueprint"]:::application
            Tasks["Tasks Blueprint"]:::application
            USSD["USSD Blueprint"]:::application
            AT["AT Commands Blueprint"]:::application
        end
        AppEntry["App Entry Point (app.py)"]:::application
        Static["Static Assets"]:::presentation
        Templates["Jinja2 Templates"]:::presentation
    end

    %% Services Layer
    subgraph "Services Layer"
        direction TB
        Scheduler["Scheduler Service"]:::services
        SerialHandler["Serial Handler"]:::services
        SIMMonitor["SIM Monitor"]:::services
        SMSParser["SMS Parser"]:::services
    end

    %% Database
    Database["MySQL/MariaDB\n(SQLAlchemy Models)"]:::database

    %% Hardware Layer
    subgraph "Hardware"
        direction TB
        Arduino["Arduino + SIM800L Modules"]:::hardware
    end

    %% Connections
    Browser -->|"HTTP Request"| FlaskApp
    External -->|"REST API Call"| FlaskApp
    FlaskApp -->|uses| Config
    FlaskApp -->|serves| Static
    FlaskApp -->|renders| Templates
    FlaskApp -->|dispatches to| Auth
    FlaskApp -->|dispatches to| Admin
    FlaskApp -->|dispatches to| Dashboard
    FlaskApp -->|dispatches to| Inbox
    FlaskApp -->|dispatches to| Reports
    FlaskApp -->|dispatches to| Settings
    FlaskApp -->|dispatches to| SIMStatus
    FlaskApp -->|dispatches to| SMS
    FlaskApp -->|dispatches to| SMSCampaign
    FlaskApp -->|dispatches to| Tasks
    FlaskApp -->|dispatches to| USSD
    FlaskApp -->|dispatches to| AT
    FlaskApp -->|reads/writes| Database
    Scheduler -->|polls| Database
    Scheduler -->|sends tasks to| SerialHandler
    SerialHandler -->|communicates with| Arduino
    SIMMonitor -->|reads metrics via| SerialHandler
    SIMMonitor -->|updates| Database
    SMSParser -->|imports CSV data to| Database

    %% Click Events
    click AppEntry "https://github.com/elmadkouryassine/sms_gateway/blob/main/app.py"
    click Config "https://github.com/elmadkouryassine/sms_gateway/blob/main/config.py"
    click Database "https://github.com/elmadkouryassine/sms_gateway/blob/main/database/models.py"
    click Auth "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/auth.py"
    click Admin "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/admin.py"
    click Dashboard "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/dashboard.py"
    click Inbox "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/inbox.py"
    click Reports "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/reports.py"
    click Settings "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/settings.py"
    click SIMStatus "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/sim_status.py"
    click SMS "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/sms.py"
    click SMSCampaign "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/sms_campaign.py"
    click Tasks "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/tasks.py"
    click USSD "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/ussd.py"
    click AT "https://github.com/elmadkouryassine/sms_gateway/blob/main/routes/at.py"
    click Scheduler "https://github.com/elmadkouryassine/sms_gateway/blob/main/services/scheduler.py"
    click Scheduler "https://github.com/elmadkouryassine/sms_gateway/blob/main/run_scheduler.py"
    click SerialHandler "https://github.com/elmadkouryassine/sms_gateway/blob/main/services/serial_handler.py"
    click SIMMonitor "https://github.com/elmadkouryassine/sms_gateway/blob/main/services/sim_monitor.py"
    click SMSParser "https://github.com/elmadkouryassine/sms_gateway/blob/main/services/sms_parser.py"
    click Static "https://github.com/elmadkouryassine/sms_gateway/tree/main/static/"
    click Templates "https://github.com/elmadkouryassine/sms_gateway/tree/main/templates/"

    %% Styles
    classDef presentation fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef application fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef services fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef database fill:#fffde7,stroke:#f9a825,color:#f57f17
    classDef hardware fill:#eceff1,stroke:#607d8b,color:#37474f
```
