# paldhaduk7-png/ai-scam-phishing-detector architecture

> Architecture diagram of the GitHub repository paldhaduk7-png/ai-scam-phishing-detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paldhaduk7-png/ai-scam-phishing-detector
- Repository: https://github.com/paldhaduk7-png/ai-scam-phishing-detector

## Overview

ScamShield is a web platform for scanning email, SMS, and URLs, then presenting threat verdicts and security activity. The main workflow runs from the React detection interface through the FastAPI API to unified ML or email-only deep-learning inference; authenticated scans are recorded for history and dashboard views. Separate product branches cover account access and profiles, Gmail import, and administrative operations. README capability descriptions supplement the sampled excerpts; some internal router-to-service wiring is not shown, so uncertain links are omitted.

Main entry points: [`backend/app/routers/auth.py`](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/auth.py) (Auth routes), [`backend/app/main.py`](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/main.py) (FastAPI gateway), [`backend/app/database.py`](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/database.py) (Database access), [`backend/app/routers/gmail.py`](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/gmail.py) (Gmail routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_frontend["React application<br/>[App.jsx]"]
  node_detect_ui["Scan interface<br/>[Detect.jsx]"]
  node_account_ui["Account and profile<br/>[authSlice.js]"]
  node_history_ui["History and dashboard<br/>[History.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and detection"]
  node_fastapi["FastAPI gateway<br/>[main.py]"]
  node_detection_routes["Detection routes<br/>[detections.py]"]
  node_unified["Detection dispatcher"]
  node_admin_routes["Admin operations<br/>[admin.py]"]
end

subgraph group_identity["Identity and integrations"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_gmail_routes["Gmail routes<br/>[gmail.py]"]
  node_gmail_service["Gmail integration<br/>[gmail_service.py]"]
  node_email_service["Email delivery<br/>[email_service.py]"]
end

subgraph group_state["Security records"]
  node_records[("User and scan records<br/>[models.py]")]
  node_database_access["Database access<br/>[database.py]"]
end

subgraph group_ml["Inference engines"]
  node_ml_detector["Traditional ML<br/>[detector.py]"]
  node_dl_detector["Deep-learning detector<br/>[dl_detector.py]"]
  node_ml_pipeline["ML pipeline<br/>[predict.py]"]
  node_dl_pipeline["DL pipeline<br/>[predict.py]"]
end

node_user(("User"))
node_google(("Google services"))
node_cloudinary(("Cloudinary"))

node_user -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_detect_ui
node_frontend -->|"checks session"| node_account_ui
node_detect_ui -->|"submits scans"| node_api_client
node_account_ui -->|"requests account"| node_api_client
node_history_ui -->|"requests records"| node_api_client
node_api_client -->|"sends HTTP"| node_fastapi
node_fastapi -->|"dispatches"| node_detection_routes
node_detection_routes -->|"runs detection"| node_unified
node_unified -->|"uses ML"| node_ml_detector
node_unified -->|"uses DL"| node_dl_detector
node_ml_detector -->|"predicts with"| node_ml_pipeline
node_dl_detector -->|"predicts with"| node_dl_pipeline
node_detection_routes -->|"records scans"| node_database_access
node_database_access -->|"reads and writes"| node_records
node_fastapi -->|"dispatches"| node_auth_routes
node_auth_routes -->|"validates sessions"| node_auth_service
node_auth_routes -->|"reads and writes"| node_database_access
node_auth_routes -.->|"sends recovery email"| node_email_service
node_auth_routes -.->|"OAuth exchange"| node_google
node_auth_routes -.->|"manages avatars"| node_cloudinary
node_fastapi -->|"dispatches"| node_gmail_routes
node_gmail_routes -->|"fetches messages"| node_gmail_service
node_gmail_service -.->|"Gmail API"| node_google
node_gmail_routes -->|"analyzes messages"| node_unified
node_gmail_routes -->|"records scans"| node_database_access
node_fastapi -->|"dispatches"| node_admin_routes
node_admin_routes -->|"reads and writes"| node_database_access

click node_frontend "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/App.jsx"
click node_detect_ui "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/pages/Detect.jsx"
click node_account_ui "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/store/slices/authSlice.js"
click node_history_ui "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/pages/History.jsx"
click node_api_client "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/services/api.js"
click node_fastapi "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/main.py"
click node_detection_routes "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/detections.py"
click node_unified "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/unified_detector.py"
click node_auth_routes "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/auth.py"
click node_auth_service "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/auth_service.py"
click node_gmail_routes "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/gmail.py"
click node_gmail_service "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/gmail_service.py"
click node_email_service "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/email_service.py"
click node_records "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/models.py"
click node_database_access "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/database.py"
click node_admin_routes "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/admin.py"
click node_ml_detector "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/detector.py"
click node_dl_detector "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/dl_detector.py"
click node_ml_pipeline "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/ml/src/predict.py"
click node_dl_pipeline "https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/dl/src/predict.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_frontend,node_detect_ui,node_account_ui,node_history_ui,node_api_client,node_user toneBlue
class node_fastapi,node_detection_routes,node_unified,node_admin_routes toneAmber
class node_auth_routes,node_auth_service,node_gmail_routes,node_gmail_service,node_email_service toneMint
class node_records,node_database_access toneRose
class node_ml_detector,node_dl_detector,node_ml_pipeline,node_dl_pipeline,node_google,node_cloudinary toneIndigo
```

## Components

### Web client

- [React application](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Scan interface](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/pages/Detect.jsx): `frontend/src/pages/Detect.jsx`
- [Account and profile](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/store/slices/authSlice.js): `frontend/src/store/slices/authSlice.js`
- [History and dashboard](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/pages/History.jsx): `frontend/src/pages/History.jsx`
- [API client](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and detection

- [FastAPI gateway](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/main.py): `backend/app/main.py`
- [Detection routes](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/detections.py): `backend/app/routers/detections.py`
- [Detection dispatcher](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/unified_detector.py): `backend/app/services/unified_detector.py`
- [Admin operations](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`

### Identity and integrations

- [Auth routes](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Auth service](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Gmail routes](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/routers/gmail.py): `backend/app/routers/gmail.py`
- [Gmail integration](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/gmail_service.py): `backend/app/services/gmail_service.py`
- [Email delivery](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`

### Security records

- [User and scan records](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database access](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/database.py): `backend/app/database.py`

### Inference engines

- [Traditional ML](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/detector.py): `backend/app/services/detector.py`
- [Deep-learning detector](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/backend/app/services/dl_detector.py): `backend/app/services/dl_detector.py`
- [ML pipeline](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/ml/src/predict.py): `ml/src/predict.py`
- [DL pipeline](https://github.com/paldhaduk7-png/ai-scam-phishing-detector/blob/main/dl/src/predict.py): `dl/src/predict.py`

### Other components

- **User**
- **Google services**
- **Cloudinary**

## Connections

- User → React application: uses
- React application → Scan interface: routes to
- React application → Account and profile: checks session
- Scan interface → API client: submits scans
- Account and profile → API client: requests account
- History and dashboard → API client: requests records
- API client → FastAPI gateway: sends HTTP
- FastAPI gateway → Detection routes: dispatches
- Detection routes → Detection dispatcher: runs detection
- Detection dispatcher → Traditional ML: uses ML
- Detection dispatcher → Deep-learning detector: uses DL
- Traditional ML → ML pipeline: predicts with
- Deep-learning detector → DL pipeline: predicts with
- Detection routes → Database access: records scans
- Database access → User and scan records: reads and writes
- FastAPI gateway → Auth routes: dispatches
- Auth routes → Auth service: validates sessions
- Auth routes → Database access: reads and writes
- Auth routes → Email delivery: sends recovery email
- Auth routes → Google services: OAuth exchange
- Auth routes → Cloudinary: manages avatars
- FastAPI gateway → Gmail routes: dispatches
- Gmail routes → Gmail integration: fetches messages
- Gmail integration → Google services: Gmail API
- Gmail routes → Detection dispatcher: analyzes messages
- Gmail routes → Database access: records scans
- FastAPI gateway → Admin operations: dispatches
- Admin operations → Database access: reads and writes