# shamim-al-mamun/twitter-truth-detector architecture

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

- Interactive diagram: https://gitdiagram.com/shamim-al-mamun/twitter-truth-detector
- Repository: https://github.com/shamim-al-mamun/twitter-truth-detector

## Overview

##### Project Type and Purpose
- This is a simple full-stack web application with an ML backend:
- Frontend: HTML/CSS user interface
- Backend: Flask server handling HTTP requests
- Machine Learning: Logistic Regression model for inference
- Offline training component to produce serialized artifacts

##### File Structure
- Top‐level files:
- app.py: Flask routes for GET (render form) and POST (predict)
- train_model.py: Preprocessing and model training pipeline
- model.pkl & vectorizer.pkl: Serialized model + TF-IDF vectorizer
- README.md, documentation.docx, data_set.docx: project docs
- Directories:
- templates/index.html: user-facing HTML form
- static/style.css: UI styling

##### Main Components
a. User Interface Layer
- Browser / User Agent
- templates/index.html + static/style.css
b. Web Server Layer
- Flask application (app.py)
- HTTP routes:
- GET / → serves index.html
- POST /predict → accepts tweet text
c. Inference Layer
- model.pkl (Logistic Regression)
- vectorizer.pkl (TF-IDF)
- In-memory data flow: incoming text → vectorizer → model → label
d. Training Pipeline (offline)
- train_model.py
- Raw labeled data (data_set.docx)
- Preprocessing: tokenization, stopword removal, TF-IDF
- Model training → produce model.pkl + vectorizer.pkl
e. (Future) External Services
- Twitter API for real-time tweet fetching (planned)

##### Relationships and Data Flows
- User → [Browser sends HTTP request] → Flask server
- Flask server → [loads vectorizer.pkl & model.pkl] → runs inference
- Server → [HTTP response with prediction] → Browser
- Training pipeline (separate process) → reads raw data → outputs pickles
- (Optional) External Twitter API → feeds into server or training pipeline

##### Architectural Patterns and Principles
- Separation of concerns: UI, HTTP routing, ML inference, and offline training are distinct
- Stateless request handling: Flask routes load artifacts at startup or per request
- Modular ML artifacts: model and vectorizer are interchangeable for retraining

- Browser / User Interface
- Flask App Server
- ML Inference (model.pkl + vectorizer.pkl)
- Training Pipeline (train_model.py + data_set.docx)
- (Optional) Twitter API external service

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["Browser / User Agent"]:::external
        TPL["templates/index.html"]:::ui
        CSS["static/style.css"]:::ui
    end

    %% Web Server Layer
    subgraph "Web Server Layer"
        App["Flask App Server (app.py)"]:::service
    end

    %% Inference Layer
    subgraph "Inference Layer"
        Vec[(vectorizer.pkl)]:::artifact
        Mod[(model.pkl)]:::artifact
    end

    %% Training Pipeline (Offline)
    subgraph "Training Pipeline (Offline)"
        Train["train_model.py"]:::service
        Data["data_set.docx"]:::artifact
    end

    %% External Services
    subgraph "External Services"
        ExtTw["Twitter API"]:::external
    end

    %% Data Flows
    UI -->|"GET /, POST /predict"| App
    App -->|"loads vectorizer.pkl"| Vec
    App -->|"loads model.pkl"| Mod
    Vec -->|"transform text"| Mod
    Mod -->|"predict label"| App
    App -->|"return prediction"| UI

    Train -->|"reads raw data"| Data
    Train -->|"outputs artifacts"| Vec
    Train -->|"outputs artifacts"| Mod

    ExtTw -.->|"fetch tweets"| App
    ExtTw -.->|"fetch tweets"| Train

    %% Click Events
    click TPL "https://github.com/shamim-al-mamun/twitter-truth-detector/blob/main/templates/index.html"
    click CSS "https://github.com/shamim-al-mamun/twitter-truth-detector/blob/main/static/style.css"
    click App "https://github.com/shamim-al-mamun/twitter-truth-detector/blob/main/app.py"
    click Vec "https://github.com/shamim-al-mamun/twitter-truth-detector/blob/main/vectorizer.pkl"
    click Mod "https://github.com/shamim-al-mamun/twitter-truth-detector/blob/main/model.pkl"
    click Train "https://github.com/shamim-al-mamun/twitter-truth-detector/blob/main/train_model.py"
    click Data "https://github.com/shamim-al-mamun/twitter-truth-detector/blob/main/data_set.docx"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef service fill:#90EE90,stroke:#000,stroke-width:1px
    classDef artifact fill:#FFD700,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
