# trideep091/scamshield architecture

> Architecture diagram of the GitHub repository trideep091/scamshield, 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/trideep091/scamshield
- Repository: https://github.com/trideep091/scamshield

## Overview

ScamShield India is a mobile-first scam-checking PWA with a FastAPI backend. Users submit message text or decoded QR content, screenshots, or APKs; backend analysis produces risk and reasons, selects response actions, stores incident metadata, and returns a verdict for the frontend checklist. Separate branches cover account-linked history and aggregate statistics, accessibility/languages, and APK inspection. Evidence is limited to the provided README and excerpts/SOURCE INDEX; several frontend integrations and backend service internals are unsampled.

Main entry points: [`backend/app/api/analyze.py`](https://github.com/trideep091/scamshield/blob/main/backend/app/api/analyze.py) (Analysis routes), [`frontend/src/components/HomeScanner.tsx`](https://github.com/trideep091/scamshield/blob/main/frontend/src/components/HomeScanner.tsx) (Multi-input scanner), [`backend/app/core/database.py`](https://github.com/trideep091/scamshield/blob/main/backend/app/core/database.py) (Database sessions), [`backend/app/services/detector.py`](https://github.com/trideep091/scamshield/blob/main/backend/app/services/detector.py) (Signal detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Scanner experience"]
  node_home["Scanner page<br/>[page.tsx]"]
  node_scanner["Multi-input scanner<br/>[HomeScanner.tsx]"]
  node_qr["QR capture<br/>[QRScannerModal.tsx]"]
  node_verdict["Verdict display<br/>[VerdictBanner.tsx]"]
  node_apkview["APK verdict<br/>[ApkVerdictCard.tsx]"]
  node_i18n["Language and accessibility<br/>[context.tsx]"]
end

subgraph group_analysis["Threat analysis"]
  node_api["FastAPI application<br/>[main.py]"]
  node_analyze["Analysis routes<br/>[analyze.py]"]
  node_detector["Signal detector<br/>[detector.py]"]
  node_baseline["Text baseline<br/>[text_baseline.py]"]
  node_url["URL heuristics<br/>[url_analyzer.py]"]
  node_classifier["ONNX classifier<br/>[onnx_classifier.py]"]
  node_apk["APK inspection<br/>[apk_analyzer.py]"]
end

subgraph group_response["Response guidance"]
  node_actions["Action engine<br/>[action_engine.py]"]
  node_checklist["Safety checklist"]
  node_actionstate["Action state selector"]
end

subgraph group_accounts["Accounts and telemetry"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_security["Identity and tokens<br/>[security.py]"]
  node_user["User records<br/>[user.py]"]
  node_stats["Statistics route<br/>[stats.py]"]
  node_incident["Incident records<br/>[incident.py]"]
  node_database[("Database sessions<br/>[database.py]")]
end

node_visitor(("Digital user"))

node_visitor -->|"opens"| node_home
node_home -->|"renders"| node_scanner
node_scanner -->|"opens"| node_qr
node_scanner -.->|"submits checks"| node_analyze
node_analyze -->|"evaluates text"| node_detector
node_detector -->|"scores text"| node_baseline
node_detector -->|"checks links"| node_url
node_detector -->|"tries model"| node_classifier
node_analyze -->|"inspects APK"| node_apk
node_detector -->|"maps risk"| node_actions
node_analyze -->|"selects actions"| node_actions
node_analyze -->|"stores metadata"| node_incident
node_analyze -->|"uses session"| node_database
node_api -->|"registers routes"| node_analyze
node_api -->|"initializes"| node_database
node_scanner -->|"renders"| node_verdict
node_scanner -->|"renders"| node_apkview
node_scanner -->|"renders"| node_checklist
node_checklist -->|"renders"| node_actionstate
node_home -->|"uses translations"| node_i18n
node_auth -->|"verifies identity"| node_security
node_auth -->|"reads and writes"| node_user
node_auth -->|"reads and deletes history"| node_incident
node_auth -->|"uses session"| node_database
node_stats -->|"aggregates"| node_incident
node_stats -.->|"uses session"| node_database
node_database -->|"registers model"| node_user
node_database -->|"registers model"| node_incident

click node_home "https://github.com/trideep091/scamshield/blob/main/frontend/src/app/page.tsx"
click node_scanner "https://github.com/trideep091/scamshield/blob/main/frontend/src/components/HomeScanner.tsx"
click node_qr "https://github.com/trideep091/scamshield/blob/main/frontend/src/components/QRScannerModal.tsx"
click node_verdict "https://github.com/trideep091/scamshield/blob/main/frontend/src/components/VerdictBanner.tsx"
click node_apkview "https://github.com/trideep091/scamshield/blob/main/frontend/src/components/ApkVerdictCard.tsx"
click node_i18n "https://github.com/trideep091/scamshield/blob/main/frontend/src/i18n/context.tsx"
click node_api "https://github.com/trideep091/scamshield/blob/main/backend/app/main.py"
click node_analyze "https://github.com/trideep091/scamshield/blob/main/backend/app/api/analyze.py"
click node_detector "https://github.com/trideep091/scamshield/blob/main/backend/app/services/detector.py"
click node_baseline "https://github.com/trideep091/scamshield/blob/main/backend/app/services/text_baseline.py"
click node_url "https://github.com/trideep091/scamshield/blob/main/backend/app/services/url_analyzer.py"
click node_classifier "https://github.com/trideep091/scamshield/blob/main/backend/app/services/onnx_classifier.py"
click node_apk "https://github.com/trideep091/scamshield/blob/main/backend/app/services/apk_analyzer.py"
click node_actions "https://github.com/trideep091/scamshield/blob/main/backend/app/services/action_engine.py"
click node_checklist "https://github.com/trideep091/scamshield/blob/main/frontend/src/components/ActionChecklist.tsx"
click node_actionstate "https://github.com/trideep091/scamshield/blob/main/frontend/src/components/ActionStateSelector.tsx"
click node_auth "https://github.com/trideep091/scamshield/blob/main/backend/app/api/auth.py"
click node_security "https://github.com/trideep091/scamshield/blob/main/backend/app/core/security.py"
click node_user "https://github.com/trideep091/scamshield/blob/main/backend/app/models/user.py"
click node_stats "https://github.com/trideep091/scamshield/blob/main/backend/app/api/stats.py"
click node_incident "https://github.com/trideep091/scamshield/blob/main/backend/app/models/incident.py"
click node_database "https://github.com/trideep091/scamshield/blob/main/backend/app/core/database.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_home,node_scanner,node_qr,node_verdict,node_apkview,node_i18n,node_visitor toneBlue
class node_api,node_analyze,node_detector,node_baseline,node_url,node_classifier,node_apk toneAmber
class node_actions,node_checklist,node_actionstate toneMint
class node_auth,node_security,node_user,node_stats,node_incident,node_database toneRose
```

## Components

### Scanner experience

- [Scanner page](https://github.com/trideep091/scamshield/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Multi-input scanner](https://github.com/trideep091/scamshield/blob/main/frontend/src/components/HomeScanner.tsx): `frontend/src/components/HomeScanner.tsx`
- [QR capture](https://github.com/trideep091/scamshield/blob/main/frontend/src/components/QRScannerModal.tsx): `frontend/src/components/QRScannerModal.tsx`
- [Verdict display](https://github.com/trideep091/scamshield/blob/main/frontend/src/components/VerdictBanner.tsx): `frontend/src/components/VerdictBanner.tsx`
- [APK verdict](https://github.com/trideep091/scamshield/blob/main/frontend/src/components/ApkVerdictCard.tsx): `frontend/src/components/ApkVerdictCard.tsx`
- [Language and accessibility](https://github.com/trideep091/scamshield/blob/main/frontend/src/i18n/context.tsx): `frontend/src/i18n/context.tsx`

### Threat analysis

- [FastAPI application](https://github.com/trideep091/scamshield/blob/main/backend/app/main.py): `backend/app/main.py`
- [Analysis routes](https://github.com/trideep091/scamshield/blob/main/backend/app/api/analyze.py): `backend/app/api/analyze.py`
- [Signal detector](https://github.com/trideep091/scamshield/blob/main/backend/app/services/detector.py): `backend/app/services/detector.py`
- [Text baseline](https://github.com/trideep091/scamshield/blob/main/backend/app/services/text_baseline.py): `backend/app/services/text_baseline.py`
- [URL heuristics](https://github.com/trideep091/scamshield/blob/main/backend/app/services/url_analyzer.py): `backend/app/services/url_analyzer.py`
- [ONNX classifier](https://github.com/trideep091/scamshield/blob/main/backend/app/services/onnx_classifier.py): `backend/app/services/onnx_classifier.py`
- [APK inspection](https://github.com/trideep091/scamshield/blob/main/backend/app/services/apk_analyzer.py): `backend/app/services/apk_analyzer.py`

### Response guidance

- [Action engine](https://github.com/trideep091/scamshield/blob/main/backend/app/services/action_engine.py): `backend/app/services/action_engine.py`
- [Safety checklist](https://github.com/trideep091/scamshield/blob/main/frontend/src/components/ActionChecklist.tsx): `frontend/src/components/ActionChecklist.tsx`
- [Action state selector](https://github.com/trideep091/scamshield/blob/main/frontend/src/components/ActionStateSelector.tsx): `frontend/src/components/ActionStateSelector.tsx`

### Accounts and telemetry

- [Authentication routes](https://github.com/trideep091/scamshield/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Identity and tokens](https://github.com/trideep091/scamshield/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [User records](https://github.com/trideep091/scamshield/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Statistics route](https://github.com/trideep091/scamshield/blob/main/backend/app/api/stats.py): `backend/app/api/stats.py`
- [Incident records](https://github.com/trideep091/scamshield/blob/main/backend/app/models/incident.py): `backend/app/models/incident.py`
- [Database sessions](https://github.com/trideep091/scamshield/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Digital user**

## Connections

- Digital user → Scanner page: opens (evidence: `frontend/src/app/page.tsx`)
- Scanner page → Multi-input scanner: renders (evidence: `frontend/src/app/page.tsx`)
- Multi-input scanner → QR capture: opens (evidence: `frontend/src/components/HomeScanner.tsx`)
- Multi-input scanner → Analysis routes: submits checks
- Analysis routes → Signal detector: evaluates text (evidence: `backend/app/api/analyze.py`)
- Signal detector → Text baseline: scores text (evidence: `backend/app/services/detector.py`)
- Signal detector → URL heuristics: checks links (evidence: `backend/app/services/detector.py`)
- Signal detector → ONNX classifier: tries model (evidence: `backend/app/services/detector.py`)
- Analysis routes → APK inspection: inspects APK (evidence: `backend/app/api/analyze.py`)
- Signal detector → Action engine: maps risk (evidence: `backend/app/services/detector.py`)
- Analysis routes → Action engine: selects actions (evidence: `backend/app/api/analyze.py`)
- Analysis routes → Incident records: stores metadata (evidence: `backend/app/api/analyze.py`)
- Analysis routes → Database sessions: uses session (evidence: `backend/app/api/analyze.py`)
- FastAPI application → Analysis routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Database sessions: initializes (evidence: `backend/app/main.py`)
- Multi-input scanner → Verdict display: renders (evidence: `frontend/src/components/HomeScanner.tsx`)
- Multi-input scanner → APK verdict: renders (evidence: `frontend/src/components/HomeScanner.tsx`)
- Multi-input scanner → Safety checklist: renders (evidence: `frontend/src/components/HomeScanner.tsx`)
- Safety checklist → Action state selector: renders (evidence: `frontend/src/components/ActionChecklist.tsx`)
- Scanner page → Language and accessibility: uses translations (evidence: `frontend/src/app/page.tsx`)
- Authentication routes → Identity and tokens: verifies identity (evidence: `backend/app/api/auth.py`)
- Authentication routes → User records: reads and writes (evidence: `backend/app/api/auth.py`)
- Authentication routes → Incident records: reads and deletes history (evidence: `backend/app/api/auth.py`)
- Authentication routes → Database sessions: uses session (evidence: `backend/app/api/auth.py`)
- Statistics route → Incident records: aggregates (evidence: `backend/app/api/stats.py`)
- Statistics route → Database sessions: uses session (evidence: `backend/app/api/stats.py`)
- Database sessions → User records: registers model (evidence: `backend/app/core/database.py`)
- Database sessions → Incident records: registers model (evidence: `backend/app/core/database.py`)
