# arka79/phishguard architecture

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

- Interactive diagram: https://gitdiagram.com/arka79/phishguard
- Repository: https://github.com/arka79/phishguard

## Overview

PHISHGUARD accepts URL scans through its web app and browser extension, analyzes URLs through deterministic engines, and combines evidence into explainable risk assessments. The analysis API owns engine orchestration; shared contracts define the data exchanged across TypeScript and Python. The web app presents scan results, while a separate ML service exposes URL classification and explanations. The README establishes multi-layer detection and explainable scoring; unsampled web and service wiring is omitted or left unverified rather than inferred.

Main entry points: [`services/analysis/app/orchestration.py`](https://github.com/arka79/phishguard/blob/main/services/analysis/app/orchestration.py) (Scan orchestration), [`services/ml/training/train.py`](https://github.com/arka79/phishguard/blob/main/services/ml/training/train.py) (Model training), [`apps/extension/src/service-worker.ts`](https://github.com/arka79/phishguard/blob/main/apps/extension/src/service-worker.ts) (Extension worker), [`packages/contracts/src/phishguard_contracts/models.py`](https://github.com/arka79/phishguard/blob/main/packages/contracts/src/phishguard_contracts/models.py) (Shared contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User-facing clients"]
  node_popup["Extension popup<br/>[popup.ts]"]
  node_worker["Extension worker<br/>[service-worker.ts]"]
  node_backend["Extension backend client<br/>[backend.ts]"]
  node_cache["Extension cache<br/>[cache.ts]"]
  node_assessment["Response validation<br/>[assessment.ts]"]
  node_web["Web scan experience<br/>[page.tsx]"]
  node_scanform["Scan form<br/>[ScanForm.tsx]"]
  node_scanapi["Scan API routes<br/>[route.ts]"]
end

subgraph group_analysis["Analysis and scoring"]
  node_analysisapi["Analysis API<br/>[main.py]"]
  node_orchestration["Scan orchestration<br/>[orchestration.py]"]
  node_urlanalysis["URL analysis<br/>[url_analysis.py]"]
  node_intel["Threat intelligence<br/>[threat_intel.py]"]
  node_risk["Risk assessment<br/>[risk_assessment.py]"]
  node_transport["Transport analysis<br/>[transport.py]"]
end

subgraph group_ml["Machine learning"]
  node_mlapi["ML inference API<br/>[main.py]"]
  node_inference["Model inference<br/>[inference.py]"]
  node_training["Model training<br/>[train.py]"]
  node_dataset["Training dataset<br/>[dataset.py]"]
  node_features["Feature extraction<br/>[features.py]"]
  node_explain["Model explanations<br/>[explain.py]"]
end

subgraph group_shared["Contracts and presentation"]
  node_results["Result presentation"]
  node_enginesui["Engine reports"]
  node_enginedetail["Engine detail<br/>[EngineDetail.tsx]"]
  node_contracts["Shared contracts<br/>[models.py]"]
end

node_user(("User"))

node_user -.->|"requests scan"| node_popup
node_popup -.->|"requests assessment"| node_worker
node_worker -->|"requests assessment"| node_backend
node_worker -->|"reads and writes"| node_cache
node_worker -->|"uses response types"| node_assessment
node_user -.->|"submits URL"| node_web
node_web -.->|"renders form"| node_scanform
node_scanform -.->|"submits scan"| node_scanapi
node_user -.->|"views result"| node_results
node_results -.->|"renders reports"| node_enginesui
node_enginesui -->|"renders details"| node_enginedetail
node_analysisapi -->|"runs scan"| node_orchestration
node_orchestration -->|"analyzes URL"| node_urlanalysis
node_orchestration -->|"gathers intelligence"| node_intel
node_orchestration -->|"assesses risk"| node_risk
node_orchestration -->|"uses transport evidence"| node_transport
node_analysisapi -->|"validates requests"| node_contracts
node_orchestration -->|"builds scan result"| node_contracts
node_mlapi -->|"serves predictions"| node_inference
node_inference -->|"builds explainer"| node_explain
node_training -->|"loads dataset"| node_dataset
node_training -->|"extracts features"| node_features
node_training -->|"creates explanations"| node_explain
node_training -->|"records model metadata"| node_contracts

click node_popup "https://github.com/arka79/phishguard/blob/main/apps/extension/src/popup.ts"
click node_worker "https://github.com/arka79/phishguard/blob/main/apps/extension/src/service-worker.ts"
click node_backend "https://github.com/arka79/phishguard/blob/main/apps/extension/src/lib/backend.ts"
click node_cache "https://github.com/arka79/phishguard/blob/main/apps/extension/src/lib/cache.ts"
click node_assessment "https://github.com/arka79/phishguard/blob/main/apps/extension/src/lib/assessment.ts"
click node_web "https://github.com/arka79/phishguard/blob/main/apps/web/app/scan/page.tsx"
click node_scanform "https://github.com/arka79/phishguard/blob/main/apps/web/components/ScanForm.tsx"
click node_scanapi "https://github.com/arka79/phishguard/blob/main/apps/web/app/api/scan/route.ts"
click node_results "https://github.com/arka79/phishguard/blob/main/apps/web/components/ScanResultDetail.tsx"
click node_enginesui "https://github.com/arka79/phishguard/blob/main/apps/web/components/scan/EngineReportsSection.tsx"
click node_enginedetail "https://github.com/arka79/phishguard/blob/main/apps/web/components/scan/EngineDetail.tsx"
click node_analysisapi "https://github.com/arka79/phishguard/blob/main/services/analysis/app/main.py"
click node_orchestration "https://github.com/arka79/phishguard/blob/main/services/analysis/app/orchestration.py"
click node_urlanalysis "https://github.com/arka79/phishguard/blob/main/services/analysis/url_analysis.py"
click node_intel "https://github.com/arka79/phishguard/blob/main/services/analysis/threat_intel.py"
click node_risk "https://github.com/arka79/phishguard/blob/main/services/analysis/risk_assessment.py"
click node_transport "https://github.com/arka79/phishguard/blob/main/services/analysis/app/transport.py"
click node_contracts "https://github.com/arka79/phishguard/blob/main/packages/contracts/src/phishguard_contracts/models.py"
click node_mlapi "https://github.com/arka79/phishguard/blob/main/services/ml/app/main.py"
click node_inference "https://github.com/arka79/phishguard/blob/main/services/ml/app/inference.py"
click node_training "https://github.com/arka79/phishguard/blob/main/services/ml/training/train.py"
click node_dataset "https://github.com/arka79/phishguard/blob/main/services/ml/training/dataset.py"
click node_features "https://github.com/arka79/phishguard/blob/main/services/ml/training/features.py"
click node_explain "https://github.com/arka79/phishguard/blob/main/services/ml/training/explain.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_worker,node_backend,node_cache,node_assessment,node_web,node_scanform,node_scanapi,node_user toneBlue
class node_analysisapi,node_orchestration,node_urlanalysis,node_intel,node_risk,node_transport toneAmber
class node_mlapi,node_inference,node_training,node_dataset,node_features,node_explain toneMint
class node_results,node_enginesui,node_enginedetail,node_contracts toneRose
```

## Components

### User-facing clients

- [Extension popup](https://github.com/arka79/phishguard/blob/main/apps/extension/src/popup.ts): `apps/extension/src/popup.ts`
- [Extension worker](https://github.com/arka79/phishguard/blob/main/apps/extension/src/service-worker.ts): `apps/extension/src/service-worker.ts`
- [Extension backend client](https://github.com/arka79/phishguard/blob/main/apps/extension/src/lib/backend.ts): `apps/extension/src/lib/backend.ts`
- [Extension cache](https://github.com/arka79/phishguard/blob/main/apps/extension/src/lib/cache.ts): `apps/extension/src/lib/cache.ts`
- [Response validation](https://github.com/arka79/phishguard/blob/main/apps/extension/src/lib/assessment.ts): `apps/extension/src/lib/assessment.ts`
- [Web scan experience](https://github.com/arka79/phishguard/blob/main/apps/web/app/scan/page.tsx): `apps/web/app/scan/page.tsx`
- [Scan form](https://github.com/arka79/phishguard/blob/main/apps/web/components/ScanForm.tsx): `apps/web/components/ScanForm.tsx`
- [Scan API routes](https://github.com/arka79/phishguard/blob/main/apps/web/app/api/scan/route.ts): `apps/web/app/api/scan/route.ts`

### Analysis and scoring

- [Analysis API](https://github.com/arka79/phishguard/blob/main/services/analysis/app/main.py): `services/analysis/app/main.py`
- [Scan orchestration](https://github.com/arka79/phishguard/blob/main/services/analysis/app/orchestration.py): `services/analysis/app/orchestration.py`
- [URL analysis](https://github.com/arka79/phishguard/blob/main/services/analysis/url_analysis.py): `services/analysis/url_analysis.py`
- [Threat intelligence](https://github.com/arka79/phishguard/blob/main/services/analysis/threat_intel.py): `services/analysis/threat_intel.py`
- [Risk assessment](https://github.com/arka79/phishguard/blob/main/services/analysis/risk_assessment.py): `services/analysis/risk_assessment.py`
- [Transport analysis](https://github.com/arka79/phishguard/blob/main/services/analysis/app/transport.py): `services/analysis/app/transport.py`

### Machine learning

- [ML inference API](https://github.com/arka79/phishguard/blob/main/services/ml/app/main.py): `services/ml/app/main.py`
- [Model inference](https://github.com/arka79/phishguard/blob/main/services/ml/app/inference.py): `services/ml/app/inference.py`
- [Model training](https://github.com/arka79/phishguard/blob/main/services/ml/training/train.py): `services/ml/training/train.py`
- [Training dataset](https://github.com/arka79/phishguard/blob/main/services/ml/training/dataset.py): `services/ml/training/dataset.py`
- [Feature extraction](https://github.com/arka79/phishguard/blob/main/services/ml/training/features.py): `services/ml/training/features.py`
- [Model explanations](https://github.com/arka79/phishguard/blob/main/services/ml/training/explain.py): `services/ml/training/explain.py`

### Contracts and presentation

- [Result presentation](https://github.com/arka79/phishguard/blob/main/apps/web/components/ScanResultDetail.tsx): `apps/web/components/ScanResultDetail.tsx`
- [Engine reports](https://github.com/arka79/phishguard/blob/main/apps/web/components/scan/EngineReportsSection.tsx): `apps/web/components/scan/EngineReportsSection.tsx`
- [Engine detail](https://github.com/arka79/phishguard/blob/main/apps/web/components/scan/EngineDetail.tsx): `apps/web/components/scan/EngineDetail.tsx`
- [Shared contracts](https://github.com/arka79/phishguard/blob/main/packages/contracts/src/phishguard_contracts/models.py): `packages/contracts/src/phishguard_contracts/models.py`

### Other components

- **User**

## Connections

- User → Extension popup: requests scan
- Extension popup → Extension worker: requests assessment
- Extension worker → Extension backend client: requests assessment (evidence: `apps/extension/src/service-worker.ts`)
- Extension worker → Extension cache: reads and writes (evidence: `apps/extension/src/service-worker.ts`)
- Extension worker → Response validation: uses response types (evidence: `apps/extension/src/service-worker.ts`)
- User → Web scan experience: submits URL
- Web scan experience → Scan form: renders form
- Scan form → Scan API routes: submits scan
- User → Result presentation: views result
- Result presentation → Engine reports: renders reports
- Engine reports → Engine detail: renders details (evidence: `apps/web/components/scan/EngineReportsSection.tsx`)
- Analysis API → Scan orchestration: runs scan (evidence: `services/analysis/app/main.py`)
- Scan orchestration → URL analysis: analyzes URL (evidence: `services/analysis/app/orchestration.py`)
- Scan orchestration → Threat intelligence: gathers intelligence (evidence: `services/analysis/app/orchestration.py`)
- Scan orchestration → Risk assessment: assesses risk (evidence: `services/analysis/app/orchestration.py`)
- Scan orchestration → Transport analysis: uses transport evidence (evidence: `services/analysis/app/orchestration.py`)
- Analysis API → Shared contracts: validates requests (evidence: `services/analysis/app/main.py`)
- Scan orchestration → Shared contracts: builds scan result (evidence: `services/analysis/app/orchestration.py`)
- ML inference API → Model inference: serves predictions (evidence: `services/ml/app/main.py`)
- Model inference → Model explanations: builds explainer (evidence: `services/ml/app/inference.py`)
- Model training → Training dataset: loads dataset (evidence: `services/ml/training/train.py`)
- Model training → Feature extraction: extracts features (evidence: `services/ml/training/train.py`)
- Model training → Model explanations: creates explanations (evidence: `services/ml/training/train.py`)
- Model training → Shared contracts: records model metadata (evidence: `services/ml/training/train.py`)