# navyaxdev/safora architecture

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

- Interactive diagram: https://gitdiagram.com/navyaxdev/safora
- Repository: https://github.com/navyaxdev/safora

## Overview

SAFORA is a Chrome extension backed by a Flask phishing-analysis API. The main workflow scans visited pages or user-submitted links, scores URL features with an ML model, independently generates plain-language rule explanations, and presents risk results and warnings. The extension also documents context-menu scans, tab-isolated persistent results, and a second warning on sensitive input. A separate website explains the product and includes a live scanner demo. Backend and extension calls are visible in excerpts; some browser event wiring and the website demo’s API connection are documented or unsampled, so those links are marked unverified.

Main entry points: [`frontend/src/App.jsx`](https://github.com/navyaxdev/safora/blob/main/frontend/src/App.jsx) (Popup Controller), [`backend/app.py`](https://github.com/navyaxdev/safora/blob/main/backend/app.py) (Prediction API), [`frontend/public/background.js`](https://github.com/navyaxdev/safora/blob/main/frontend/public/background.js) (Scan Coordinator), [`website/src/App.jsx`](https://github.com/navyaxdev/safora/blob/main/website/src/App.jsx) (Product Site)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Chrome Extension"]
  node_content["Page Monitoring<br/>[content.js]"]
  node_background["Scan Coordinator<br/>[background.js]"]
  node_popup["Popup Controller<br/>[App.jsx]"]
  node_dashboard["Dashboard"]
  node_manual["Manual URL Scan<br/>[ShowUrlCard.jsx]"]
  node_warning["Threat Warning"]
  node_about["Extension About<br/>[AboutPageCard.jsx]"]
  node_storage[("Chrome Storage")]
end

subgraph group_analysis["URL Analysis"]
  node_api["Prediction API<br/>[app.py]"]
  node_features["Feature Extraction<br/>[app.py]"]
  node_model["ML Risk Scoring<br/>[app.py]"]
  node_rules["Rule Explanations<br/>[phishing_rules.py]"]
  node_result["Risk Result"]
end

subgraph group_website["Product Website"]
  node_site["Product Site<br/>[App.jsx]"]
  node_sitecontent["Product Sections<br/>[Features.jsx]"]
  node_risklevels["Risk Levels<br/>[RiskLevels.jsx]"]
end

subgraph group_webdemo["Website Scanner"]
  node_live["Live Scanner Demo"]
  node_webapi["Website API Client<br/>[api.js]"]
end

node_browser(("Browsing User"))
node_chrome["Chrome Browser"]

node_browser -->|"browses"| node_chrome
node_chrome -->|"loads pages"| node_content
node_content -.->|"requests scans"| node_background
node_background -.->|"submits URL"| node_api
node_api -->|"extracts features"| node_features
node_api -->|"scores features"| node_model
node_api -->|"gets reasons"| node_rules
node_model -->|"supplies score"| node_result
node_rules -->|"supplies reasons"| node_result
node_api -->|"returns JSON"| node_result
node_background -.->|"persists scans"| node_storage
node_popup -->|"reads scan state"| node_storage
node_popup -->|"reads theme"| node_storage
node_popup -->|"renders"| node_dashboard
node_popup -->|"renders"| node_manual
node_popup -->|"renders"| node_warning
node_popup -->|"renders"| node_about
node_manual -->|"posts URL"| node_api
node_warning -->|"closes tab"| node_chrome
node_chrome -.->|"routes scan actions"| node_background
node_site -->|"renders sections"| node_sitecontent
node_site -->|"renders"| node_risklevels
node_site -->|"opens demo"| node_live
node_live -.->|"uses API client"| node_webapi

click node_content "https://github.com/navyaxdev/safora/blob/main/frontend/public/content.js"
click node_background "https://github.com/navyaxdev/safora/blob/main/frontend/public/background.js"
click node_popup "https://github.com/navyaxdev/safora/blob/main/frontend/src/App.jsx"
click node_dashboard "https://github.com/navyaxdev/safora/blob/main/frontend/src/components/SaforaDashboard.jsx"
click node_manual "https://github.com/navyaxdev/safora/blob/main/frontend/src/components/ShowUrlCard.jsx"
click node_warning "https://github.com/navyaxdev/safora/blob/main/frontend/src/components/SpottedAThreadCard.jsx"
click node_about "https://github.com/navyaxdev/safora/blob/main/frontend/src/components/AboutPageCard.jsx"
click node_api "https://github.com/navyaxdev/safora/blob/main/backend/app.py"
click node_features "https://github.com/navyaxdev/safora/blob/main/backend/app.py"
click node_model "https://github.com/navyaxdev/safora/blob/main/backend/app.py"
click node_rules "https://github.com/navyaxdev/safora/blob/main/backend/phishing_rules.py"
click node_site "https://github.com/navyaxdev/safora/blob/main/website/src/App.jsx"
click node_sitecontent "https://github.com/navyaxdev/safora/blob/main/website/src/components/safora/Features.jsx"
click node_risklevels "https://github.com/navyaxdev/safora/blob/main/website/src/components/safora/RiskLevels.jsx"
click node_live "https://github.com/navyaxdev/safora/blob/main/website/src/components/LiveScannerDemo.jsx"
click node_webapi "https://github.com/navyaxdev/safora/blob/main/website/src/lib/api.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_content,node_background,node_popup,node_dashboard,node_manual,node_warning,node_about,node_storage,node_browser,node_chrome toneBlue
class node_api,node_features,node_model,node_rules,node_result toneAmber
class node_site,node_sitecontent,node_risklevels toneMint
class node_live,node_webapi toneRose
```

## Components

### Chrome Extension

- [Page Monitoring](https://github.com/navyaxdev/safora/blob/main/frontend/public/content.js): `frontend/public/content.js`
- [Scan Coordinator](https://github.com/navyaxdev/safora/blob/main/frontend/public/background.js): `frontend/public/background.js`
- [Popup Controller](https://github.com/navyaxdev/safora/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Dashboard](https://github.com/navyaxdev/safora/blob/main/frontend/src/components/SaforaDashboard.jsx): `frontend/src/components/SaforaDashboard.jsx`
- [Manual URL Scan](https://github.com/navyaxdev/safora/blob/main/frontend/src/components/ShowUrlCard.jsx): `frontend/src/components/ShowUrlCard.jsx`
- [Threat Warning](https://github.com/navyaxdev/safora/blob/main/frontend/src/components/SpottedAThreadCard.jsx): `frontend/src/components/SpottedAThreadCard.jsx`
- [Extension About](https://github.com/navyaxdev/safora/blob/main/frontend/src/components/AboutPageCard.jsx): `frontend/src/components/AboutPageCard.jsx`
- **Chrome Storage**

### URL Analysis

- [Prediction API](https://github.com/navyaxdev/safora/blob/main/backend/app.py): `backend/app.py`
- [Feature Extraction](https://github.com/navyaxdev/safora/blob/main/backend/app.py): `backend/app.py`
- [ML Risk Scoring](https://github.com/navyaxdev/safora/blob/main/backend/app.py): `backend/app.py`
- [Rule Explanations](https://github.com/navyaxdev/safora/blob/main/backend/phishing_rules.py): `backend/phishing_rules.py`
- **Risk Result**

### Product Website

- [Product Site](https://github.com/navyaxdev/safora/blob/main/website/src/App.jsx): `website/src/App.jsx`
- [Product Sections](https://github.com/navyaxdev/safora/blob/main/website/src/components/safora/Features.jsx): `website/src/components/safora/Features.jsx`
- [Risk Levels](https://github.com/navyaxdev/safora/blob/main/website/src/components/safora/RiskLevels.jsx): `website/src/components/safora/RiskLevels.jsx`

### Website Scanner

- [Live Scanner Demo](https://github.com/navyaxdev/safora/blob/main/website/src/components/LiveScannerDemo.jsx): `website/src/components/LiveScannerDemo.jsx`
- [Website API Client](https://github.com/navyaxdev/safora/blob/main/website/src/lib/api.js): `website/src/lib/api.js`

### Other components

- **Browsing User**
- **Chrome Browser**

## Connections

- Browsing User → Chrome Browser: browses (evidence: `README.md`)
- Chrome Browser → Page Monitoring: loads pages (evidence: `README.md`)
- Page Monitoring → Scan Coordinator: requests scans
- Scan Coordinator → Prediction API: submits URL (evidence: `README.md`)
- Prediction API → Feature Extraction: extracts features (evidence: `backend/app.py`)
- Prediction API → ML Risk Scoring: scores features (evidence: `backend/app.py`)
- Prediction API → Rule Explanations: gets reasons (evidence: `backend/app.py`)
- ML Risk Scoring → Risk Result: supplies score (evidence: `backend/app.py`)
- Rule Explanations → Risk Result: supplies reasons
- Prediction API → Risk Result: returns JSON (evidence: `backend/app.py`)
- Scan Coordinator → Chrome Storage: persists scans (evidence: `README.md`)
- Popup Controller → Chrome Storage: reads scan state (evidence: `frontend/src/App.jsx`)
- Popup Controller → Chrome Storage: reads theme (evidence: `frontend/src/App.jsx`)
- Popup Controller → Dashboard: renders (evidence: `frontend/src/App.jsx`)
- Popup Controller → Manual URL Scan: renders (evidence: `frontend/src/App.jsx`)
- Popup Controller → Threat Warning: renders (evidence: `frontend/src/App.jsx`)
- Popup Controller → Extension About: renders (evidence: `frontend/src/App.jsx`)
- Manual URL Scan → Prediction API: posts URL (evidence: `frontend/src/components/ShowUrlCard.jsx`)
- Threat Warning → Chrome Browser: closes tab (evidence: `frontend/src/components/SpottedAThreadCard.jsx`)
- Chrome Browser → Scan Coordinator: routes scan actions (evidence: `README.md`)
- Product Site → Product Sections: renders sections (evidence: `website/src/App.jsx`)
- Product Site → Risk Levels: renders (evidence: `website/src/App.jsx`)
- Product Site → Live Scanner Demo: opens demo (evidence: `website/src/App.jsx`)
- Live Scanner Demo → Website API Client: uses API client
