# shantanujoshi25/webscout architecture

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

- Interactive diagram: https://gitdiagram.com/shantanujoshi25/webscout
- Repository: https://github.com/shantanujoshi25/webscout

## Overview

##### Project type and purpose
- WebScout is a hybrid system consisting of a Chrome extension (frontend) and a local Python/Flask backend.
- Its purpose is to scan web pages for common security vulnerabilities by injecting scripts into the page, collecting DOM/data, then performing advanced analysis (including AI‐enhanced detection) on a local server.

##### File structure
- Top‐level:
- README.md (project overview)
- backend/ (Flask application + virtual environment)
- extension/ (Chrome extension code and assets)
- extension/ contains:
- manifest.json (extension configuration)
- background.js (persistent background script handling messages/events)
- content.js (injected into web pages to scrape DOM/data)
- popup/ (UI layer: popup.html, popup.js, popup.css)
- backend/ contains:
- app.py (Flask app exposing scan API endpoints)
- venv/ (Python dependencies)

##### Key insights from README
- The extension UI allows manual or auto‐scan via a “Scan Current Page” button.
- The backend server runs at http://127.0.0.1:5000 and processes scan requests, leveraging AI/ML.
- No external cloud services are mentioned—analysis is done locally.

##### Main components and their interactions
a. Browser with WebScout extension
- Popup UI (popup.html/js/css) for user controls (scan depth, toggles).
- Background script for orchestrating scan events and managing long‐running tasks.
- Content script for DOM inspection and payload collection.
b. Local Flask backend
- Exposes REST endpoints (e.g., /scan) that accept page data.
- Houses the scanning engine and AI models for vulnerability detection.
c. User’s target web page
- The content script is injected into pages the user visits.
d. (Optional) Local storage or file system for exportable reports

Interaction flow:
2. User requests “Scan Current Page.”
3. Popup script signals background script to initiate scan.
4. Background script injects content script (if not already injected).
5. Content script gathers DOM snapshots, form metadata, headers, etc.
6. Background script sends an HTTP POST to Flask backend at localhost:5000/scan with the collected data.
7. Backend processes data (fast checks + AI analysis) → returns JSON report.
8. Background script receives report → forwards it to popup UI.
9. Popup UI displays vulnerabilities and remediation steps.
10. User can export the report (saved locally via extension APIs or download).

##### Architectural patterns and principles
- Separation of concerns: UI (popup), orchestration (background), data‐collection (content), analysis (backend).
- Client‐server model: lightweight extension as client, Flask server as analysis engine.
- Message‐passing within the extension (Chrome runtime messaging).
- REST API between extension and backend.

##### Technologies & frameworks
- Chrome Extension APIs (manifest v3 or v2)
- JavaScript for popup, background, and content scripts
- Flask (Python) for backend server and REST endpoints
- AI/ML libraries (in Python environment) for enhanced detection
- Optional: local storage or file export libraries

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser & Extension"
        direction TB
        PopupUI["Popup UI"]:::ext
        Background["Background Script"]:::ext
        Content["Content Script"]:::ext
        Manifest["manifest.json"]:::ext
        Icons["icons/"]:::ext
    end

    subgraph "Target Web Page"
        direction TB
        WebPage["Target Web Page"]:::external
    end

    subgraph "Flask Backend"
        direction TB
        Backend["Flask Backend (port 5000)"]:::backend
        Venv["venv/"]:::backend
    end

    Storage["Local Storage / Report"]:::storage
    README["README.md"]:::docs

    %% Interactions
    PopupUI -->|"Chrome.runtime.sendMessage"| Background
    Background -->|"Inject content.js"| WebPage
    Background -->|"Chrome.runtime.sendMessage"| Content
    WebPage -->|"Page Data"| Content
    Content -->|"Collected Data"| Background
    Background -->|"HTTP POST /scan"| Backend
    Backend -->|"JSON Report"| Background
    Background -->|"sendMessage(report)"| PopupUI
    PopupUI -->|"Download via Chrome API"| Storage

    %% Click Events
    click PopupUI "https://github.com/shantanujoshi25/webscout/blob/main/extension/popup/popup.html"
    click Background "https://github.com/shantanujoshi25/webscout/blob/main/extension/background.js"
    click Content "https://github.com/shantanujoshi25/webscout/blob/main/extension/content.js"
    click Manifest "https://github.com/shantanujoshi25/webscout/blob/main/extension/manifest.json"
    click Icons "https://github.com/shantanujoshi25/webscout/tree/main/extension/icons/"
    click Backend "https://github.com/shantanujoshi25/webscout/blob/main/backend/app.py"
    click Venv "https://github.com/shantanujoshi25/webscout/tree/main/backend/venv/"
    click README "https://github.com/shantanujoshi25/webscout/blob/main/README.md"

    %% Styles
    classDef ext fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef backend fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef storage fill:#FFF4B3,stroke:#333,stroke-width:1px
    classDef docs fill:#F2F2F2,stroke:#333,stroke-width:1px
```
