# safiullahaamir/tweetviralitypredictor architecture

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

- Interactive diagram: https://gitdiagram.com/safiullahaamir/tweetviralitypredictor
- Repository: https://github.com/safiullahaamir/tweetviralitypredictor

## Overview

##### Project Type and Purpose
- This is a machine-learning-powered Streamlit web application that predicts tweet virality (Viral vs Non-Viral).
- It comprises a small training pipeline (in a Jupyter notebook and Python scripts), serialized artifacts (model and vectorizer), and a Streamlit front end for inference.

##### Main Components
a. Frontend (Streamlit UI)
- TweetViralityPredictor_App.py: defines the web interface, input fields, and displays prediction.
- Hosted on Streamlit Cloud (tweet-virality-predictor.streamlit.app).
b. Model Artifacts (Storage)
- tfidf_vectorizer.pkl: serializes the TF-IDF transformer.
- logistic_regression_model.pkl: serializes the trained classifier.
c. Data & Training Pipeline
- main.ipynb: data preprocessing, EDA, feature engineering, model training, evaluation.
- tweet_content-engagement_dataset.csv: the training dataset.
d. Dependency & Configuration
- requirements.txt: Python dependencies (pandas, numpy, scikit-learn, streamlit, etc.).
- .devcontainer: development environment setup for VS Code (optional).

##### Relationships & Data Flow
1. User enters tweet text and numeric features in the Streamlit UI.
2. TweetViralityPredictor_App.py loads tfidf_vectorizer.pkl to transform text → feature vector.
3. The vector and numeric inputs feed into logistic_regression_model.pkl for inference.
4. Prediction (“Viral”/“Non-Viral”) is returned to the UI.
5. (Offline) main.ipynb reads the CSV → trains model → serializes artifacts.

##### Architectural Patterns & Design Principles
- Separation of Concerns: distinct phases for training (in notebook) vs. inference (in app script).
- Layered Architecture:
- Presentation Layer (Streamlit UI)
- Application Layer (prediction logic in Python script)
- Data Layer (serialized model & vectorizer, CSV dataset)
- Reproducibility: environment pinned in requirements.txt and devcontainer.json.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Production - Inference
    subgraph "Streamlit Inference"
        direction TB
        User["User"]:::frontend
        StreamlitApp["Streamlit App"]:::frontend
        PredictionService["Prediction Service (Python)"]:::ml
        Vectorizer["TF-IDF Vectorizer"]:::datastore
        Model["Logistic Regression Model"]:::datastore
    end

    %% Offline Training
    subgraph "Offline Training"
        direction TB
        Notebook["Training Notebook (main.ipynb)"]:::ml
        Dataset["Tweet Content & Engagement Dataset"]:::datastore
        Requirements["requirements.txt"]:::dev
        DevContainer["devcontainer.json"]:::dev
    end

    %% Inference Flow
    User -->|"enters tweet text & features"| StreamlitApp
    StreamlitApp -->|"invoke prediction"| PredictionService
    PredictionService -->|"load vectorizer"| Vectorizer
    Vectorizer -->|"transform text"| PredictionService
    PredictionService -->|"load model"| Model
    PredictionService -->|"predict class"| PredictionService
    PredictionService -->|"return result"| StreamlitApp

    %% Training Flow
    Notebook -->|"reads data"| Dataset
    Notebook -->|"train & serialize"| Vectorizer
    Notebook -->|"train & serialize"| Model
    Notebook -->|"use env config"| Requirements
    Notebook -->|"use devcontainer"| DevContainer

    %% Click Events
    click StreamlitApp "https://github.com/safiullahaamir/tweetviralitypredictor/blob/main/TweetViralityPredictor_App.py"
    click Vectorizer "https://github.com/safiullahaamir/tweetviralitypredictor/blob/main/tfidf_vectorizer.pkl"
    click Model "https://github.com/safiullahaamir/tweetviralitypredictor/blob/main/logistic_regression_model.pkl"
    click Notebook "https://github.com/safiullahaamir/tweetviralitypredictor/blob/main/main.ipynb"
    click Dataset "https://github.com/safiullahaamir/tweetviralitypredictor/blob/main/tweet_content-engagement_dataset.csv"
    click Requirements "https://github.com/safiullahaamir/tweetviralitypredictor/blob/main/requirements.txt"
    click DevContainer "https://github.com/safiullahaamir/tweetviralitypredictor/blob/main/.devcontainer/devcontainer.json"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef ml fill:#90EE90,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#000,stroke-width:1px
    classDef dev fill:#D3D3D3,stroke:#000,stroke-width:1px
```
