# regcyb1/safesurf architecture

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

- Interactive diagram: https://gitdiagram.com/regcyb1/safesurf
- Repository: https://github.com/regcyb1/safesurf

## Overview

##### Project Type and Purpose
- SafeSurf is a browser extension that classifies web pages (e.g., phishing vs. safe) using machine-learning models.
- It includes:
- A training pipeline (Python scripts, datasets)
- Model artifacts (pickled Random Forest and MLP models)
- A browser extension (HTML/JS/CSS) for end-user interaction
- Lightweight testing modules

##### Main Components
A. Training Pipeline (Offline)
1. Raw datasets (ARFF files in train/data, plus combined_dataset.csv)
2. Feature extraction module (test/features_extraction.py & patterns.py)
3. Model training scripts (train/train_rf.py, train/train_mlp.py)
4. Output: model artifacts (models/random_forest.pkl, models/mlp_model.pkl)

B. Deployment Runtime
1. Browser Extension (extension/manifest.json, popup.html, popup.js, style.css)
- UI popup for user to trigger classification
- JS sends the current URL/content for analysis
2. Local Classification Service (invoked via run.sh)
- A minimal Python HTTP server or CLI that:
- Loads the pickled models
- Applies the same feature-extraction logic
- Returns classification results (safe/phishing)
3. Optional Logging/Storage (not yet implemented, could be added)

##### Relationships & Data Flows
- Offline: Dataset → Feature Extraction → Training Scripts → Model Artifacts
- Runtime: User clicks extension popup → JS sends URL → Classification Service loads Model → Returns verdict → Extension displays result

##### Architectural Patterns & Design Principles
- Clear separation of concerns:
- Offline training vs. online serving
- UI (extension) vs. business logic (classification service)
- Reuse of code: feature extraction logic is shared between test suite, training, and serving
- Extensibility: New models can be added to /models and automatically served

## Diagram (Mermaid)

```mermaid
graph TB
  %% Offline Training
  subgraph "Offline Training"
    direction TB
    CombinedCSV["combined_dataset.csv"]:::data
    ARFF1["web_data.arff"]:::data
    ARFF2["web_data2.arff"]:::data
    FeaturesExtraction["features_extraction.py"]:::code
    Patterns["patterns.py"]:::code
    TestModule["test.py"]:::code
    subgraph "Training Scripts"
      direction TB
      TrainRF["train_rf.py"]:::code
      TrainMLP["train_mlp.py"]:::code
    end
    RFModel["random_forest.pkl"]:::data
    MLPModel["mlp_model.pkl"]:::data
  end

  %% Deployment Runtime
  subgraph "Deployment Runtime"
    direction TB
    Manifest["manifest.json"]:::code
    PopupHTML["popup.html"]:::code
    PopupJS["popup.js"]:::code
    StyleCSS["style.css"]:::code
    runService["Classification Service\n(/predict)"]:::service
    LoadedModels["Loaded Models (.pkl)"]:::data
  end

  %% Offline Data Flows
  CombinedCSV -->|feeds| FeaturesExtraction
  ARFF1 -->|feeds| FeaturesExtraction
  ARFF2 -->|feeds| FeaturesExtraction
  FeaturesExtraction -->|uses| Patterns
  FeaturesExtraction -->|validated by| TestModule
  FeaturesExtraction -->|trains| TrainRF
  FeaturesExtraction -->|trains| TrainMLP
  TrainRF -->|outputs| RFModel
  TrainMLP -->|outputs| MLPModel

  %% Runtime Data Flows
  Manifest --> PopupHTML
  Manifest --> PopupJS
  Manifest --> StyleCSS
  PopupHTML -->|loads| PopupJS
  PopupJS -->|calls| runService
  RFModel -->|loaded by| LoadedModels
  MLPModel -->|loaded by| LoadedModels
  LoadedModels -->|used by| runService
  runService -->|returns verdict| PopupJS
  PopupJS -->|displays result| PopupHTML

  %% Click Events
  click CombinedCSV "https://github.com/regcyb1/safesurf/blob/main/combined_dataset.csv"
  click ARFF1 "https://github.com/regcyb1/safesurf/blob/main/train/data/web_data.arff"
  click ARFF2 "https://github.com/regcyb1/safesurf/blob/main/train/data/web_data2.arff"
  click FeaturesExtraction "https://github.com/regcyb1/safesurf/blob/main/test/features_extraction.py"
  click Patterns "https://github.com/regcyb1/safesurf/blob/main/test/patterns.py"
  click TestModule "https://github.com/regcyb1/safesurf/blob/main/test/test.py"
  click TrainRF "https://github.com/regcyb1/safesurf/blob/main/train/train_rf.py"
  click TrainMLP "https://github.com/regcyb1/safesurf/blob/main/train/train_mlp.py"
  click RFModel "https://github.com/regcyb1/safesurf/blob/main/models/random_forest.pkl"
  click MLPModel "https://github.com/regcyb1/safesurf/blob/main/models/mlp_model.pkl"
  click Manifest "https://github.com/regcyb1/safesurf/blob/main/extension/manifest.json"
  click PopupHTML "https://github.com/regcyb1/safesurf/blob/main/extension/popup.html"
  click PopupJS "https://github.com/regcyb1/safesurf/blob/main/extension/popup.js"
  click StyleCSS "https://github.com/regcyb1/safesurf/blob/main/extension/style.css"
  click runService "https://github.com/regcyb1/safesurf/blob/main/run.sh"

  %% Styles
  classDef data fill:#FFF0B3,stroke:#E0C080;
  classDef code fill:#F0F0F0,stroke:#CCCCCC;
  classDef service fill:#E0FFE0,stroke:#80C080;
  class OfflineTraining data,code;
  class DeploymentRuntime service,data,code;
```
