# shubhh004/scamshield-ai architecture

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

## Overview

ScamShield AI is a web platform for multimodal scam detection. Users enter through the React application, authenticate for protected tools, submit URL, email, SMS, QR, or image content for analysis, and can review scan history, dashboard summaries, analytics, and AI explanations. The server separates route/controller handling from feature services and persists user and scan data. README capability descriptions establish the product scope; the client-to-server request wiring and several scanner internals were not excerpted, so those links are omitted or marked unverified.

Main entry points: [`client/src/features`](https://github.com/shubhh004/scamshield-ai/tree/develop/client/src/features) (Scanner pages), [`client/src/App.tsx`](https://github.com/shubhh004/scamshield-ai/blob/develop/client/src/App.tsx) (App routing), [`server/src/features/history/history.model.ts`](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/history/history.model.ts) (Scan records), [`client/src/features/auth/pages`](https://github.com/shubhh004/scamshield-ai/tree/develop/client/src/features/auth/pages) (Login and registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["App routing<br/>[App.tsx]"]
  node_authui["Login and registration"]
  node_scanui["Scanner pages"]
  node_insightsui["History and insights"]
end

subgraph group_scanning["Threat scanning"]
  node_urlscan["URL analysis"]
  node_riskengine["URL risk engine<br/>[risk.engine.ts]"]
  node_emailscan["Email analysis"]
  node_smsscan["SMS analysis"]
  node_qrscan["QR decoding"]
  node_ocrscan["Image OCR"]
  node_filescan["File scanning"]
end

subgraph group_accounts["Accounts and insights"]
  node_authapi["Authentication API<br/>[auth.controller.ts]"]
  node_userstore[("User records<br/>[user.model.ts]")]
  node_history["Scan history<br/>[history.service.ts]"]
  node_scanrecords[("Scan records<br/>[history.model.ts]")]
  node_dashboard["Dashboard summary"]
  node_analytics["Analytics"]
end

subgraph group_server["API and persistence"]
  node_ai["AI explanations<br/>[ai.service.ts]"]
  node_dbconfig["Database configuration<br/>[db.ts]"]
end

node_user(("Platform user"))
node_groq{{"Groq inference"}}

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_scanui
node_app -->|"routes to"| node_insightsui
node_authui -.->|"submits credentials"| node_authapi
node_scanui -.->|"submits scans"| node_urlscan
node_scanui -.->|"submits scans"| node_emailscan
node_scanui -.->|"submits scans"| node_smsscan
node_scanui -.->|"submits images"| node_qrscan
node_scanui -.->|"submits images"| node_ocrscan
node_scanui -.->|"submits files"| node_filescan
node_insightsui -.->|"requests history"| node_history
node_authapi -->|"reads and writes"| node_userstore
node_history -->|"reads and writes"| node_scanrecords
node_dashboard -->|"reads"| node_scanrecords
node_urlscan -.->|"assesses risk"| node_riskengine
node_ai -.->|"requests inference"| node_groq
node_dbconfig -.->|"configures storage"| node_scanrecords

click node_app "https://github.com/shubhh004/scamshield-ai/blob/develop/client/src/App.tsx"
click node_authui "https://github.com/shubhh004/scamshield-ai/tree/develop/client/src/features/auth/pages"
click node_scanui "https://github.com/shubhh004/scamshield-ai/tree/develop/client/src/features"
click node_insightsui "https://github.com/shubhh004/scamshield-ai/tree/develop/client/src/features"
click node_authapi "https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/auth/auth.controller.ts"
click node_userstore "https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/auth/user.model.ts"
click node_urlscan "https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-url"
click node_riskengine "https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/scan-url/risk.engine.ts"
click node_emailscan "https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-email"
click node_smsscan "https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-sms"
click node_qrscan "https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-qr"
click node_ocrscan "https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-image"
click node_filescan "https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-file"
click node_history "https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/history/history.service.ts"
click node_scanrecords "https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/history/history.model.ts"
click node_dashboard "https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/dashboard/dashboard.service.ts"
click node_analytics "https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/analytics"
click node_ai "https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/ai/ai.service.ts"
click node_dbconfig "https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/config/db.ts"

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_app,node_authui,node_scanui,node_insightsui,node_user toneBlue
class node_urlscan,node_riskengine,node_emailscan,node_smsscan,node_qrscan,node_ocrscan,node_filescan toneAmber
class node_authapi,node_userstore,node_history,node_scanrecords,node_dashboard,node_analytics toneMint
class node_ai,node_dbconfig toneRose
class node_groq toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/shubhh004/scamshield-ai/blob/develop/client/src/App.tsx): `client/src/App.tsx`
- [Login and registration](https://github.com/shubhh004/scamshield-ai/tree/develop/client/src/features/auth/pages): `client/src/features/auth/pages`
- [Scanner pages](https://github.com/shubhh004/scamshield-ai/tree/develop/client/src/features): `client/src/features`
- [History and insights](https://github.com/shubhh004/scamshield-ai/tree/develop/client/src/features): `client/src/features`

### Threat scanning

- [URL analysis](https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-url): `server/src/features/scan-url`
- [URL risk engine](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/scan-url/risk.engine.ts): `server/src/features/scan-url/risk.engine.ts`
- [Email analysis](https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-email): `server/src/features/scan-email`
- [SMS analysis](https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-sms): `server/src/features/scan-sms`
- [QR decoding](https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-qr): `server/src/features/scan-qr`
- [Image OCR](https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-image): `server/src/features/scan-image`
- [File scanning](https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/scan-file): `server/src/features/scan-file`

### Accounts and insights

- [Authentication API](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/auth/auth.controller.ts): `server/src/features/auth/auth.controller.ts`
- [User records](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/auth/user.model.ts): `server/src/features/auth/user.model.ts`
- [Scan history](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/history/history.service.ts): `server/src/features/history/history.service.ts`
- [Scan records](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/history/history.model.ts): `server/src/features/history/history.model.ts`
- [Dashboard summary](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/dashboard/dashboard.service.ts): `server/src/features/dashboard/dashboard.service.ts`
- [Analytics](https://github.com/shubhh004/scamshield-ai/tree/develop/server/src/features/analytics): `server/src/features/analytics`

### API and persistence

- [AI explanations](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/features/ai/ai.service.ts): `server/src/features/ai/ai.service.ts`
- [Database configuration](https://github.com/shubhh004/scamshield-ai/blob/develop/server/src/config/db.ts): `server/src/config/db.ts`

### Other components

- **Platform user**
- **Groq inference**

## Connections

- Platform user → App routing: uses
- App routing → Login and registration: routes to (evidence: `client/src/App.tsx`)
- App routing → Scanner pages: routes to (evidence: `client/src/App.tsx`)
- App routing → History and insights: routes to (evidence: `client/src/App.tsx`)
- Login and registration → Authentication API: submits credentials
- Scanner pages → URL analysis: submits scans
- Scanner pages → Email analysis: submits scans
- Scanner pages → SMS analysis: submits scans
- Scanner pages → QR decoding: submits images
- Scanner pages → Image OCR: submits images
- Scanner pages → File scanning: submits files
- History and insights → Scan history: requests history
- Authentication API → User records: reads and writes
- Scan history → Scan records: reads and writes (evidence: `server/src/features/history/history.service.ts`)
- Dashboard summary → Scan records: reads (evidence: `server/src/features/dashboard/dashboard.service.ts`)
- URL analysis → URL risk engine: assesses risk (evidence: `server/src/features/scan-url/risk.engine.ts`)
- AI explanations → Groq inference: requests inference
- Database configuration → Scan records: configures storage
