# sarthak-genai-33/whatsapp-education-bot architecture

> Architecture diagram of the GitHub repository sarthak-genai-33/whatsapp-education-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sarthak-genai-33/whatsapp-education-bot
- Repository: https://github.com/sarthak-genai-33/whatsapp-education-bot

## Overview

##### Project Type & Purpose
- This is a single-service backend application (no separate frontend) implemented in Python using Flask.
- It functions as a WhatsApp messaging bot for the education domain, handling incoming webhooks from Twilio’s WhatsApp API and dispatching context-aware replies across seven major educational use cases.

##### File Structure Analysis
Top‐level files only—no nested “src” or “services” directories. All core logic lives in:
- app.py             – Flask app, webhook endpoint (/whatsapp)
- requirements.txt   – Twilio SDK, Flask, Gunicorn dependencies
- Procfile, runtime.txt, railway.toml  – Deployment configuration for Heroku/Railway
- README.md          – Project description, usage, and flow examples

##### Key Architecture Insights from README
- Webhook-driven: Twilio forwards incoming WhatsApp messages to your Flask endpoint.
- In-memory data structures (sessions, menus) today, with plans for an external database.
- Hosted behind Gunicorn and a PaaS (Heroku, Railway).
- Local dev uses ngrok to expose a secure tunnel for Twilio.

1. WhatsApp User (Mobile App)
2. Twilio WhatsApp API (Cloud Service)
3. Flask Web Server
- Webhook Controller (/whatsapp endpoint)
- Message Processing Module (parsing “Body”, routing to feature handlers)
- Feature Handlers (Student Support, Admissions, Exams, Fees, etc.)
4. In-Memory Data Store (Session state, menu definitions)
5. Optional Future Components (PostgreSQL/MySQL/MongoDB, Admin Dashboard)
6. Deployment Environment
- Gunicorn WSGI server
- PaaS (Heroku/Railway)
7. Developer Tools (ngrok for local tunneling)

##### Architectural Patterns & Principles
- Event-driven webhook architecture.
- Modular handlers per feature domain.
- Dependency inversion for data store (in-memory today, swappable with real DB).
- Stateless web tier behind a WSGI server (Gunicorn).
- Clear separation of external services vs. internal logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    User["WhatsApp User\n(Mobile App)"]:::external
    Twilio["Twilio WhatsApp API"]:::external
    TwilioConsole["Twilio Console"]:::external
    Ngrok["ngrok\n(Local Dev Tunnel)"]:::devtools

    %% Flask Application Container
    subgraph "Flask App (app.py)"
        Controller["Webhook Controller\n(POST /whatsapp)"]:::api
        Processor["Message Processor"]:::logic
        Handlers["Feature Handlers\n(Student Support, Admissions,\nExams, Fees, etc.)"]:::logic
    end

    %% Data Stores
    InMemory["In-Memory Data Store\n(Session state, Menus)"]:::datastore
    FutureDB["Future Database\n(PostgreSQL/MySQL/MongoDB)"]:::datastore

    %% Deployment Environment
    subgraph "Deployment Environment"
        PaaS["PaaS\n(Heroku/Railway)"]:::deployment
        Gunicorn["Gunicorn WSGI Server"]:::deployment
        Procfile["Procfile"]:::deployment
        Runtime["runtime.txt"]:::deployment
        RailwayToml["railway.toml"]:::deployment
        Requirements["requirements.txt"]:::deployment
    end

    %% Documentation
    Readme["README.md"]:::documentation

    %% Data Flows
    User -->|"WhatsApp message"| Twilio
    Twilio -->|"HTTP POST /whatsapp"| Controller
    Controller -->|"parses request"| Processor
    Processor -->|"routes to handler"| Handlers
    Handlers -->|"reads/writes session"| InMemory
    Handlers -->|future| FutureDB
    Handlers -->|"Twilio REST API: send reply"| Twilio
    Twilio -->|"delivers reply"| User

    %% Local Dev Flow
    Twilio -->|webhook to localhost| Ngrok
    Ngrok -->|tunnels to| Controller

    %% Deployment Flow
    Readme -->|"CI/CD (Git push)"| PaaS
    PaaS -->|deploy container| Gunicorn
    Gunicorn -->|runs| Controller

    %% Configuration Node to PaaS
    Procfile --> PaaS
    Runtime --> PaaS
    RailwayToml --> PaaS
    Requirements --> PaaS

    %% Webhook Configuration
    TwilioConsole -->|"configure webhook URL"| Twilio

    %% Click Events
    click Controller "https://github.com/sarthak-genai-33/whatsapp-education-bot/blob/main/app.py"
    click Requirements "https://github.com/sarthak-genai-33/whatsapp-education-bot/blob/main/requirements.txt"
    click Procfile "https://github.com/sarthak-genai-33/whatsapp-education-bot/tree/main/Procfile"
    click Runtime "https://github.com/sarthak-genai-33/whatsapp-education-bot/blob/main/runtime.txt"
    click RailwayToml "https://github.com/sarthak-genai-33/whatsapp-education-bot/blob/main/railway.toml"
    click Readme "https://github.com/sarthak-genai-33/whatsapp-education-bot/blob/main/README.md"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,shape:ellipse
    classDef api fill:#cce5ff,stroke:#0066cc,stroke-width:2px
    classDef logic fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef datastore fill:#ffe5b4,stroke:#e69500,stroke-width:2px,shape:cylinder
    classDef deployment fill:#e6ccff,stroke:#8000ff,stroke-width:2px
    classDef devtools fill:#fce4ec,stroke:#e91e63,stroke-width:2px
    classDef documentation fill:#f0f0f0,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
```
