# akshat12bhardwaj/webguard-ai architecture

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

- Interactive diagram: https://gitdiagram.com/akshat12bhardwaj/webguard-ai
- Repository: https://github.com/akshat12bhardwaj/webguard-ai

## Overview

WebGuard AI is a Chrome extension backed by a local FastAPI service. A user submits a URL, with an optional bounded DOM snapshot for manual inspection; the backend gathers model, URL-rule, page-rule, and reputation evidence, fuses it into an assessment, and the extension presents findings and coverage. The repository also includes an external-data collection and held-out evaluation workflow. Relationships below follow README architecture statements and the shown source index/excerpts; unsampled implementation details are not assumed.

Main entry points: [`backend/service.py`](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/service.py) (Evidence collection), [`extension/api.js`](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/api.js) (API client), [`backend/api.py`](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/api.py) (FastAPI endpoints), [`ml/feature_extraction.py`](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/feature_extraction.py) (Hostname features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chrome extension"]
  node_popup["Risk popup<br/>[popup.js]"]
  node_report["Detailed report<br/>[report.js]"]
  node_client_api["API client<br/>[api.js]"]
  node_dom_inspection["Manual inspection<br/>[dom_inspection.js]"]
  node_dom_extract["DOM snapshot<br/>[dom_extractor.js]"]
  node_consumer["Finding presentation<br/>[consumer.js]"]
  node_report_model["Report model<br/>[report_model.js]"]
end

subgraph group_analysis["Assessment backend"]
  node_backend_api["FastAPI endpoints<br/>[api.py]"]
  node_analyzer["Evidence collection<br/>[service.py]"]
  node_dom_rules["Page security rules<br/>[dom_rules.py]"]
  node_dom_schema["DOM evidence schema<br/>[dom_schema.py]"]
  node_url_rules["URL security rules<br/>[rules.py]"]
  node_reputation["Threat reputation<br/>[threat_intel.py]"]
  node_evidence["Structured evidence<br/>[evidence.py]"]
  node_hybrid["Risk fusion<br/>[hybrid.py]"]
  node_fusion["Category scoring<br/>[fusion.py]"]
end

subgraph group_model["URL model"]
  node_features["Hostname features"]
  node_predict["URL inference<br/>[predict.py]"]
end

subgraph group_research["Model evaluation"]
  node_external_data["External data sets<br/>[external_data.py]"]
  node_phase_collect["Fresh-data collection<br/>[phase6_collect.py]"]
  node_phase_evaluate["Held-out evaluation<br/>[phase6_evaluate.py]"]
end

node_user(("Chrome user"))

node_user -->|"opens"| node_popup
node_popup -->|"submits URL"| node_client_api
node_report -->|"requests assessment"| node_client_api
node_dom_inspection -->|"extracts structure"| node_dom_extract
node_dom_inspection -->|"sends snapshot"| node_client_api
node_client_api -->|"POSTs analysis"| node_backend_api
node_backend_api -->|"dispatches analysis"| node_analyzer
node_backend_api -->|"evaluates page evidence"| node_dom_rules
node_backend_api -->|"fuses assessment"| node_hybrid
node_dom_rules -->|"uses schema"| node_dom_schema
node_analyzer -->|"extracts features"| node_features
node_analyzer -->|"gets prediction"| node_predict
node_analyzer -->|"evaluates URL"| node_url_rules
node_analyzer -->|"runs lookups"| node_reputation
node_analyzer -->|"assembles evidence"| node_evidence
node_hybrid -->|"delegates scoring"| node_fusion
node_url_rules -->|"uses URL features"| node_features
node_reputation -->|"returns TI results"| node_evidence
node_predict -->|"extracts features"| node_features
node_backend_api -->|"returns evidence"| node_evidence
node_client_api -->|"formats findings"| node_consumer
node_client_api -->|"builds report data"| node_report_model
node_consumer -->|"supplies presentation"| node_popup
node_report_model -->|"supplies report data"| node_report
node_external_data -->|"builds test data"| node_features
node_phase_collect -->|"normalizes collected data"| node_features
node_phase_evaluate -->|"uses collected data"| node_phase_collect
node_phase_evaluate -->|"scores candidates"| node_predict

click node_popup "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/popup.js"
click node_report "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/report.js"
click node_client_api "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/api.js"
click node_dom_inspection "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/dom_inspection.js"
click node_dom_extract "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/dom_extractor.js"
click node_consumer "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/consumer.js"
click node_report_model "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/report_model.js"
click node_backend_api "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/api.py"
click node_analyzer "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/service.py"
click node_dom_rules "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/dom_rules.py"
click node_dom_schema "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/dom_schema.py"
click node_url_rules "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/rules.py"
click node_reputation "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/threat_intel.py"
click node_evidence "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/evidence.py"
click node_hybrid "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/hybrid.py"
click node_fusion "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/fusion.py"
click node_features "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/feature_extraction.py"
click node_predict "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/predict.py"
click node_external_data "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/external_data.py"
click node_phase_collect "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/phase6_collect.py"
click node_phase_evaluate "https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/phase6_evaluate.py"

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_popup,node_report,node_client_api,node_dom_inspection,node_dom_extract,node_consumer,node_report_model,node_user toneBlue
class node_backend_api,node_analyzer,node_dom_rules,node_dom_schema,node_url_rules,node_reputation,node_evidence,node_hybrid,node_fusion toneAmber
class node_features,node_predict toneMint
class node_external_data,node_phase_collect,node_phase_evaluate toneRose
```

## Components

### Chrome extension

- [Risk popup](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/popup.js): `extension/popup.js`
- [Detailed report](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/report.js): `extension/report.js`
- [API client](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/api.js): `extension/api.js`
- [Manual inspection](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/dom_inspection.js): `extension/dom_inspection.js`
- [DOM snapshot](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/dom_extractor.js): `extension/dom_extractor.js`
- [Finding presentation](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/consumer.js): `extension/consumer.js`
- [Report model](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/extension/report_model.js): `extension/report_model.js`

### Assessment backend

- [FastAPI endpoints](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/api.py): `backend/api.py`
- [Evidence collection](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/service.py): `backend/service.py`
- [Page security rules](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/dom_rules.py): `backend/dom_rules.py`
- [DOM evidence schema](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/dom_schema.py): `backend/dom_schema.py`
- [URL security rules](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/rules.py): `backend/rules.py`
- [Threat reputation](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/threat_intel.py): `backend/threat_intel.py`
- [Structured evidence](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/evidence.py): `backend/evidence.py`
- [Risk fusion](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/hybrid.py): `backend/hybrid.py`
- [Category scoring](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/backend/fusion.py): `backend/fusion.py`

### URL model

- [Hostname features](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/feature_extraction.py): `ml/feature_extraction.py`
- [URL inference](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/predict.py): `ml/predict.py`

### Model evaluation

- [External data sets](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/external_data.py): `ml/external_data.py`
- [Fresh-data collection](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/phase6_collect.py): `ml/phase6_collect.py`
- [Held-out evaluation](https://github.com/akshat12bhardwaj/webguard-ai/blob/main/ml/phase6_evaluate.py): `ml/phase6_evaluate.py`

### Other components

- **Chrome user**

## Connections

- Chrome user → Risk popup: opens (evidence: `README.md`)
- Risk popup → API client: submits URL (evidence: `extension/popup.js`)
- Detailed report → API client: requests assessment (evidence: `extension/report.js`)
- Manual inspection → DOM snapshot: extracts structure (evidence: `extension/dom_inspection.js`)
- Manual inspection → API client: sends snapshot (evidence: `README.md`)
- API client → FastAPI endpoints: POSTs analysis (evidence: `README.md`)
- FastAPI endpoints → Evidence collection: dispatches analysis (evidence: `backend/api.py`)
- FastAPI endpoints → Page security rules: evaluates page evidence (evidence: `backend/api.py`)
- FastAPI endpoints → Risk fusion: fuses assessment (evidence: `backend/api.py`)
- Page security rules → DOM evidence schema: uses schema (evidence: `backend/dom_rules.py`)
- Evidence collection → Hostname features: extracts features (evidence: `backend/service.py`)
- Evidence collection → URL inference: gets prediction (evidence: `backend/service.py`)
- Evidence collection → URL security rules: evaluates URL (evidence: `backend/service.py`)
- Evidence collection → Threat reputation: runs lookups (evidence: `backend/service.py`)
- Evidence collection → Structured evidence: assembles evidence (evidence: `backend/service.py`)
- Risk fusion → Category scoring: delegates scoring (evidence: `backend/hybrid.py`)
- URL security rules → Hostname features: uses URL features (evidence: `backend/rules.py`)
- Threat reputation → Structured evidence: returns TI results (evidence: `backend/threat_intel.py`)
- URL inference → Hostname features: extracts features (evidence: `ml/predict.py`)
- FastAPI endpoints → Structured evidence: returns evidence (evidence: `backend/api.py`)
- API client → Finding presentation: formats findings (evidence: `extension/consumer.js`)
- API client → Report model: builds report data (evidence: `extension/report_model.js`)
- Finding presentation → Risk popup: supplies presentation (evidence: `extension/popup.js`)
- Report model → Detailed report: supplies report data (evidence: `extension/report.js`)
- External data sets → Hostname features: builds test data (evidence: `ml/external_data.py`)
- Fresh-data collection → Hostname features: normalizes collected data (evidence: `ml/phase6_collect.py`)
- Held-out evaluation → Fresh-data collection: uses collected data (evidence: `ml/phase6_evaluate.py`)
- Held-out evaluation → URL inference: scores candidates (evidence: `ml/phase6_evaluate.py`)
