# andy-techen/better-social-media architecture

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

- Interactive diagram: https://gitdiagram.com/andy-techen/better-social-media
- Repository: https://github.com/andy-techen/better-social-media

## Overview

##### Project type and purpose
- This is a full-stack application combining a Chrome extension (frontend) with a Flask-based RESTful API (backend) that hosts pre-trained machine-learning models for text classification.
- Purpose: filter a user’s Twitter feed in real time for toxicity, profanity, depressiveness, and sexual explicitness by whiting out tweets whose predicted scores exceed user-adjustable thresholds.

##### File structure
- Top-level:
- dist/ – Compiled Chrome extension (HTML, CSS, JS, manifest.json, images)
- data/ModelAPI/ – Flask app code (api.py, Procfile, requirements.txt), model artifacts (pickled XGBoost models & TF-IDF vectorizers)
- data/GitBucketData/ & data/PerspectiveAPI/ – Jupyter notebooks and raw CSV datasets used for offline model training
- package.json & package-lock.json – frontend build/config (if using Node tooling)
- requirements.txt – Python dependencies (Flask, XGBoost, NLTK, etc.)
- Architectural pattern: clear separation of concerns—UI and client logic in the extension vs. ML inference/service layer in the Flask API.

##### Key insights from README
- The Chrome extension injects UI controls (sliders) into Twitter’s DOM, observes tweets via content scripts, and makes POST requests to two endpoints (`/api/depressive` and `/api/toxicity-profane-sexually`).
- The backend loads pickled TF-IDF vectorizers and XGBoost classifiers at startup and returns JSON scores.
- Models were trained offline in Jupyter notebooks on two datasets (self-annotated tweets & PerspectiveAPI-scored Reddit comments) and packaged into .pickle files.

##### Diagramming recommendations
- Use clear labels for each component (e.g., “Content Script,” “Flask Inference Engine”).
- UI → content script → background → API request
- API response → background → content script → UI updates
– Extension UI & scripts (e.g., blue)
– Backend service & artifacts (e.g., green)
- External dependencies (Heroku, Perspective API used offline).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Chrome Extension Layer
    subgraph "Chrome Extension" 
        direction TB
        Manifest["Manifest (manifest.json)"]:::extension
        OptionsUI["Options UI (options.html)"]:::extension
        PopupUI["UI Injection (index.html)"]:::extension
        ContentScript["Content Script (twitter.js)"]:::extension
        BackgroundScript["Background Script (background.js)"]:::extension
        FrontendLogic1["Popup Logic (index.js)"]:::extension
        FrontendLogic2["Options Logic (options.js)"]:::extension
        Styles["Stylesheet (main.css)"]:::extension
    end

    %% Backend API Service Layer
    subgraph "Flask API Service" 
        direction TB
        APIServer["API Server (api.py)"]:::backend
        Procfile["Heroku Procfile"]:::backend
        Dependencies["Python Dependencies"]:::backend
        NLTKResources["NLTK Resources Spec"]:::backend
        PickleFeature["Feature Matrix (feature.pickle)"]:::backend
        subgraph "Model Artifacts" 
            direction TB
            XGB1["Depressive XGB"]:::backend
            XGB2["Toxicity XGB"]:::backend
            XGB3["Profanity XGB"]:::backend
            XGB4["Sexual XGB"]:::backend
            Vec1["Vectorizer Depressive"]:::backend
            Vec2["Vectorizer PerspectiveAPI"]:::backend
        end
    end

    %% Offline Training Pipeline
    subgraph "Offline Training Pipeline" 
        direction TB
        subgraph "Self-Annotated Training"
            direction TB
            Notebook1["Depressive Notebook"]:::offline
            CSV1["DATD CSVs"]:::offline
        end
        subgraph "PerspectiveAPI Training"
            direction TB
            Notebook2["PerspectiveAPI Notebooks"]:::offline
            RawData1["RC_2017-01_scored.csv"]:::offline
            RawData2["scored_tweets.csv"]:::offline
            ScoringScript["Tweet Scorer Script"]:::offline
            LabelScript["Labeling Script"]:::offline
        end
    end

    %% Runtime Flow
    Manifest --> PopupUI
    Manifest --> OptionsUI
    PopupUI --> ContentScript
    OptionsUI --> FrontendLogic2
    PopupUI --> FrontendLogic1
    ContentScript --> BackgroundScript
    BackgroundScript -->|POST tweet text| APIServer
    APIServer --> XGB1
    APIServer --> XGB2
    APIServer --> XGB3
    APIServer --> XGB4
    APIServer --> Vec1
    APIServer --> Vec2
    APIServer -->|return JSON scores| BackgroundScript
    BackgroundScript --> ContentScript
    ContentScript -->|whites out tweets| PopupUI

    %% Offline Flow
    Notebook1 --> CSV1
    Notebook1 -->|train vectorizer & XGB| Vec1
    Notebook1 -->|train model| XGB1
    Notebook2 --> RawData1
    Notebook2 --> RawData2
    Notebook2 -->|train vectorizer| Vec2
    Notebook2 -->|train models| XGB2
    Notebook2 -->|train models| XGB3
    Notebook2 -->|train models| XGB4
    RawData1 --> ScoringScript
    ScoringScript --> Notebook2
    LabelScript --> Notebook2

    %% Click Events
    click Manifest "https://github.com/andy-techen/better-social-media/blob/main/dist/manifest.json"
    click BackgroundScript "https://github.com/andy-techen/better-social-media/blob/main/dist/background.js"
    click ContentScript "https://github.com/andy-techen/better-social-media/blob/main/dist/scripts/twitter.js"
    click PopupUI "https://github.com/andy-techen/better-social-media/blob/main/dist/index.html"
    click OptionsUI "https://github.com/andy-techen/better-social-media/blob/main/dist/options.html"
    click FrontendLogic1 "https://github.com/andy-techen/better-social-media/blob/main/dist/scripts/index.js"
    click FrontendLogic2 "https://github.com/andy-techen/better-social-media/blob/main/dist/scripts/options.js"
    click Styles "https://github.com/andy-techen/better-social-media/blob/main/dist/styles/main.css"
    click APIServer "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/api.py"
    click Procfile "https://github.com/andy-techen/better-social-media/tree/main/data/ModelAPI/Procfile"
    click Dependencies "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/requirements.txt"
    click NLTKResources "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/nltk.txt"
    click PickleFeature "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/feature.pickle"
    click XGB1 "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/models/depressive_xgb.pickle"
    click XGB2 "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/models/toxicity_xgb.pickle"
    click XGB3 "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/models/profanity_xgb.pickle"
    click XGB4 "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/models/sexually_explicit_xgb.pickle"
    click Vec1 "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/vectorizers/vectorizer_depressive.pickle"
    click Vec2 "https://github.com/andy-techen/better-social-media/blob/main/data/ModelAPI/vectorizers/PerspectiveAPI_vectorizer.pickle"
    click Notebook1 "https://github.com/andy-techen/better-social-media/blob/main/data/GitBucketData/depressive_model.ipynb"
    click CSV1 "https://github.com/andy-techen/better-social-media/tree/main/data/GitBucketData/DATD"
    click Notebook2 "https://github.com/andy-techen/better-social-media/tree/main/data/PerspectiveAPI"
    click RawData1 "https://github.com/andy-techen/better-social-media/blob/main/data/PerspectiveAPI/RC_2017-01_scored.csv"
    click RawData2 "https://github.com/andy-techen/better-social-media/blob/main/data/PerspectiveAPI/scored_tweets.csv"
    click ScoringScript "https://github.com/andy-techen/better-social-media/blob/main/data/PerspectiveAPI/tweet_scorer.py"
    click LabelScript "https://github.com/andy-techen/better-social-media/blob/main/data/PerspectiveAPI/api.py"

    %% Styles
    classDef extension fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#E0F8E0,stroke:#2C7A0B,color:#2C7A0B;
    classDef offline fill:#F0F0F0,stroke:#888888,color:#555555,stroke-dasharray: 5 5;
```
