# ayushx15/plotera-lead-automation architecture

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

- Interactive diagram: https://gitdiagram.com/ayushx15/plotera-lead-automation
- Repository: https://github.com/ayushx15/plotera-lead-automation

## Overview

##### Project Type & Purpose
- This is a backend-only RESTful service built in Python/Flask.
- Its responsibilities are:
- Managing leads and sales-person assignments
- Exposing HTTP endpoints for CRUD operations
- Running a daily scheduler to send SMS reminders via Twilio
- Persisting data in MySQL and logging key events

##### File Structure
- Top-level files:
- app.py — Flask application entry point (routes registration, server startup)
- config.py — environment and DB/Twilio credentials loader
- requirements.txt — dependency list
- Directories:
- routes/ — HTTP route modules (leads.py, sales.py)
- db/ — data layer (db_connection.py, init_db.sql)
- utils/ — business utilities (sms.py for Twilio integration)
- cron/ — scheduled job (send_reminders.py)
- logs/ — runtime logs (app.log)
- tests/ — placeholder for unit/integration tests

##### Extract Architecture Details from README
- Tech stack: Flask (web server), MySQL (persistent store), Twilio (SMS), dotenv (config), Python logging
- Features: REST API, daily cron SMS, one-off test SMS, logging

a. Main Components
1. Client (Postman, Browser, Mobile)
2. Flask API Server
– Route Handlers: /add-lead, /get-leads, /update-status, /assign-salesperson, etc.
– Business Logic Layer (integrated in routes + utils)
3. MySQL Database (db_connection.py)
4. SMS Service (Twilio API via utils/sms.py)
5. Cron Scheduler (cron/send_reminders.py)
6. Configuration Store (.env via config.py)
7. Logging Sink (logs/app.log)
b. Interactions & Data Flows
- Client → HTTP → Flask API → CRUD → MySQL ← init_db.sql
- Flask API → utils/sms.py → Twilio REST API → SMS delivered
- Cron Scheduler (OS cron or manual invocation) → Python script →
– Query MySQL for today’s visits → for each record:
→ utils/sms.py → Twilio
→ Logging service
- config.py centrally provides DB credentials & Twilio keys to all components
c. Architectural Patterns & Principles
– Layered separation:
- Presentation/API layer (Flask + routes/)
- Data access layer (db/db_connection.py)
- Integration layer (utils/sms.py)
- Scheduled tasks separate from request flow (cron/)
– Single Responsibility: each module has focused duties
– External-Service isolation: Twilio calls encapsulated in utils
d. Key Technologies & Frameworks
– Python 3.x + Flask for HTTP server
– MySQL for relational storage
– Twilio REST API for SMS
– dotenv for secure environment variables
– Python logging module for audit trail

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients"
        direction TB
        Postman["Postman"]:::external
        Browser["Browser"]:::external
        Mobile["Mobile App"]:::external
    end

    %% Configuration and Initialization
    Config["Configuration Store\n(config.py)"]:::config
    Requirements["requirements.txt"]:::config
    Tests["tests/"]:::config

    %% API Server Layer
    subgraph "Flask API Server"
        direction TB
        FlaskAPI["Flask API Server\n(app.py)"]:::internal
        LeadsRoute["Route: /leads\n(routes/leads.py)"]:::internal
        SalesRoute["Route: /sales\n(routes/sales.py)"]:::internal
        DBConnection["Data Access\n(db/db_connection.py)"]:::internal
        SMSModule["SMS Integration\n(utils/sms.py)"]:::internal
        TestSMS["One-Off Test SMS\n(send_test_sms.py)"]:::internal
        Logging["Logging Sink\n(logs/app.log)"]:::logging
    end

    %% Scheduler Layer
    CronJob["Cron Scheduler\n(cron/send_reminders.py)"]:::internal

    %% Persistence & External Services
    subgraph "Persistence & External"
        direction TB
        DB["MySQL Database"]:::database
        InitDB["DB Setup Script\n(db/init_db.sql)"]:::database
        Twilio["Twilio SMS API"]:::external
    end

    %% Client to API
    Postman -->|HTTP Request| FlaskAPI
    Browser -->|HTTP Request| FlaskAPI
    Mobile -->|HTTP Request| FlaskAPI

    %% Config injection
    Config --> FlaskAPI
    Config --> CronJob

    %% API internals
    FlaskAPI --> LeadsRoute
    FlaskAPI --> SalesRoute
    LeadsRoute --> DBConnection
    SalesRoute --> DBConnection
    DBConnection -->|SQL Queries| DB
    FlaskAPI --> SMSModule
    SMSModule -->|REST API Calls| Twilio
    FlaskAPI --> Logging

    %% Test SMS
    TestSMS --> SMSModule
    TestSMS --> Logging

    %% Cron flow
    CronJob --> DBConnection
    CronJob --> SMSModule
    CronJob --> Logging

    %% DB initialization
    InitDB --> DB

    %% Class Definitions
    classDef internal fill:#E3F2FD,stroke:#90CAF9,stroke-width:2px;
    classDef database fill:#E8F5E9,stroke:#66BB6A,stroke-width:2px;
    classDef external fill:#FFF3E0,stroke:#FFA726,stroke-width:2px;
    classDef config fill:#ECEFF1,stroke:#78909C,stroke-width:2px;
    classDef logging fill:#F5F5F5,stroke:#BDBDBD,stroke-width:2px;

    %% Click Events
    click FlaskAPI "https://github.com/ayushx15/plotera-lead-automation/blob/main/app.py"
    click Config "https://github.com/ayushx15/plotera-lead-automation/blob/main/config.py"
    click LeadsRoute "https://github.com/ayushx15/plotera-lead-automation/blob/main/routes/leads.py"
    click SalesRoute "https://github.com/ayushx15/plotera-lead-automation/blob/main/routes/sales.py"
    click DBConnection "https://github.com/ayushx15/plotera-lead-automation/blob/main/db/db_connection.py"
    click InitDB "https://github.com/ayushx15/plotera-lead-automation/blob/main/db/init_db.sql"
    click SMSModule "https://github.com/ayushx15/plotera-lead-automation/blob/main/utils/sms.py"
    click CronJob "https://github.com/ayushx15/plotera-lead-automation/blob/main/cron/send_reminders.py"
    click TestSMS "https://github.com/ayushx15/plotera-lead-automation/blob/main/send_test_sms.py"
    click Requirements "https://github.com/ayushx15/plotera-lead-automation/blob/main/requirements.txt"
    click Tests "https://github.com/ayushx15/plotera-lead-automation/tree/main/tests/"
```
