How arka79/phishguard works
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: orchestration.py Scan orchestration · train.py Model training · service-worker.ts Extension worker · models.py Shared contracts
Components 25
User-facing clients
- Extension popup
apps/extension/src/popup.ts - Extension worker
apps/extension/src/service-worker.ts - Extension backend client
apps/extension/src/lib/backend.ts - Extension cache
apps/extension/src/lib/cache.ts - Response validation
apps/extension/src/lib/assessment.ts - Web scan experience
apps/web/app/scan/page.tsx - Scan form
apps/web/components/ScanForm.tsx - Scan API routes
apps/web/app/api/scan/route.ts
Analysis and scoring
- Analysis API
services/analysis/app/main.py - Scan orchestration
services/analysis/app/orchestration.py - URL analysis
services/analysis/url_analysis.py - Threat intelligence
services/analysis/threat_intel.py - Risk assessment
services/analysis/risk_assessment.py - Transport analysis
services/analysis/app/transport.py
Machine learning
- ML inference API
services/ml/app/main.py - Model inference
services/ml/app/inference.py - Model training
services/ml/training/train.py - Training dataset
services/ml/training/dataset.py - Feature extraction
services/ml/training/features.py - Model explanations
services/ml/training/explain.py
Contracts and presentation
- Result presentation
apps/web/components/ScanResultDetail.tsx - Engine reports
apps/web/components/scan/EngineReportsSection.tsx - Engine detail
apps/web/components/scan/EngineDetail.tsx - Shared contracts
packages/contracts/src/phishguard_contracts/models.py
Other components
- User
Connections 24
- User → Extension popup: requests scan
- Extension popup → Extension worker: requests assessment
- Extension worker → Extension backend client: requests assessment
apps/extension/src/service-worker.ts - Extension worker → Extension cache: reads and writes
apps/extension/src/service-worker.ts - Extension worker → Response validation: uses response types
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
apps/web/components/scan/EngineReportsSection.tsx - Analysis API → Scan orchestration: runs scan
services/analysis/app/main.py - Scan orchestration → URL analysis: analyzes URL
services/analysis/app/orchestration.py - Scan orchestration → Threat intelligence: gathers intelligence
services/analysis/app/orchestration.py - Scan orchestration → Risk assessment: assesses risk
services/analysis/app/orchestration.py - Scan orchestration → Transport analysis: uses transport evidence
services/analysis/app/orchestration.py - Analysis API → Shared contracts: validates requests
services/analysis/app/main.py - Scan orchestration → Shared contracts: builds scan result
services/analysis/app/orchestration.py - ML inference API → Model inference: serves predictions
services/ml/app/main.py - Model inference → Model explanations: builds explainer
services/ml/app/inference.py - Model training → Training dataset: loads dataset
services/ml/training/train.py - Model training → Feature extraction: extracts features
services/ml/training/train.py - Model training → Model explanations: creates explanations
services/ml/training/train.py - Model training → Shared contracts: records model metadata
services/ml/training/train.py