# sandeepkudupudi07/trapcheck architecture

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

- Interactive diagram: https://gitdiagram.com/sandeepkudupudi07/trapcheck
- Repository: https://github.com/sandeepkudupudi07/trapcheck

## Overview

TrapCheck is a multilingual scam-analysis application. A user submits a message through the React interface; the FastAPI backend validates and sanitizes it, retrieves related scam patterns, and uses an Ollama-hosted model to produce an assessment. Authenticated users can review scan history and submit reports; admins review reports separately from adding approved patterns to retrieval. The README documents these flows and security capabilities; some source details were not sampled, so unsourced internal links are omitted.

Main entry points: [`backend/main.py`](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/main.py) (FastAPI application), [`backend/rag_engine.py`](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/rag_engine.py) (RAG analysis), [`backend/auth/database.py`](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/database.py) (Account data models), [`backend/auth/routes.py`](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/routes.py) (Account endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_browser["Browser UI<br/>[App.jsx]"]
  node_analysis_ui["Analysis interface<br/>[TrapCheck.jsx]"]
  node_history_ui["History dashboard<br/>[History.jsx]"]
  node_http["API client<br/>[http.js]"]
end

subgraph group_api["API and security"]
  node_api["FastAPI application<br/>[main.py]"]
  node_rate["Rate limits<br/>[rate_limit.py]"]
  node_zero_log["Safe logging<br/>[zero_log.py]"]
  node_sanitizer["Message sanitizer<br/>[sanitizer.py]"]
  node_ephemeral["Ephemeral processing<br/>[ephemeral.py]"]
end

subgraph group_analysis["Scam analysis"]
  node_rag["RAG analysis<br/>[rag_engine.py]"]
  node_patterns["Scam patterns<br/>[scam_patterns.py]"]
  node_chroma[("Vector knowledge base<br/>[rag_engine.py]")]
  node_ollama["Ollama model"]
  node_scheduler["Threat-feed refresh<br/>[refresh.py]"]
  node_twilio["SMS and WhatsApp<br/>[twilio_handler.py]"]
end

subgraph group_accounts["Accounts and community"]
  node_account_routes["Account endpoints<br/>[routes.py]"]
  node_auth["JWT and passwords<br/>[auth.py]"]
  node_email["Reset email<br/>[email_service.py]"]
  node_account_db[("Account data models<br/>[database.py]")]
  node_report["Scam reporting"]
  node_admin["Admin review<br/>[admin_routes.py]"]
  node_sqlite[("Persistent records<br/>[database.py]")]
end

node_user(("User"))
node_twilio_service["Twilio"]
node_refresh_feed["PhishTank feed"]

node_user -->|"uses"| node_browser
node_browser -->|"renders"| node_analysis_ui
node_analysis_ui -->|"submits requests"| node_http
node_history_ui -->|"requests history"| node_http
node_http -->|"calls API"| node_api
node_api -->|"applies limits"| node_rate
node_api -->|"installs middleware"| node_zero_log
node_api -->|"sanitizes messages"| node_sanitizer
node_api -->|"analyzes message"| node_rag
node_api -->|"persists history"| node_account_db
node_api -->|"accepts reports"| node_report
node_api -->|"starts refresh"| node_scheduler
node_rag -->|"loads patterns"| node_patterns
node_rag -->|"retrieves patterns"| node_chroma
node_rag -->|"invokes model"| node_ollama
node_api -->|"processes transiently"| node_ephemeral
node_account_routes -->|"authenticates users"| node_auth
node_auth -->|"reads and writes"| node_account_db
node_account_routes -->|"sends reset email"| node_email
node_account_routes -->|"reads and writes"| node_account_db
node_account_db -->|"stores records"| node_sqlite
node_admin -->|"reviews reports"| node_account_db
node_admin -->|"adds approved patterns"| node_chroma
node_twilio_service -->|"posts webhooks"| node_twilio
node_twilio -->|"sanitizes input"| node_sanitizer
node_twilio -->|"analyzes messages"| node_rag
node_scheduler -->|"fetches threat feed"| node_refresh_feed
node_scheduler -->|"refreshes patterns"| node_chroma

click node_browser "https://github.com/sandeepkudupudi07/trapcheck/blob/main/frontend/trapcheck-frontend/src/App.jsx"
click node_analysis_ui "https://github.com/sandeepkudupudi07/trapcheck/blob/main/frontend/trapcheck-frontend/src/TrapCheck.jsx"
click node_history_ui "https://github.com/sandeepkudupudi07/trapcheck/blob/main/frontend/trapcheck-frontend/src/History.jsx"
click node_http "https://github.com/sandeepkudupudi07/trapcheck/blob/main/frontend/trapcheck-frontend/src/http.js"
click node_api "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/main.py"
click node_rate "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/rate_limit.py"
click node_zero_log "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/security/zero_log.py"
click node_sanitizer "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/security/sanitizer.py"
click node_ephemeral "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/security/ephemeral.py"
click node_rag "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/rag_engine.py"
click node_patterns "https://github.com/sandeepkudupudi07/trapcheck/blob/main/data/scam_patterns.py"
click node_chroma "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/rag_engine.py"
click node_scheduler "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/scheduler/refresh.py"
click node_twilio "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/channels/twilio_handler.py"
click node_account_routes "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/routes.py"
click node_auth "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/auth.py"
click node_email "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/email_service.py"
click node_account_db "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/database.py"
click node_report "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/security/anonymous_report.py"
click node_admin "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/admin_routes.py"
click node_sqlite "https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/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_browser,node_analysis_ui,node_history_ui,node_http,node_user toneBlue
class node_api,node_rate,node_zero_log,node_sanitizer,node_ephemeral toneAmber
class node_rag,node_patterns,node_chroma,node_ollama,node_scheduler,node_twilio toneMint
class node_account_routes,node_auth,node_email,node_account_db,node_report,node_admin,node_sqlite toneRose
class node_twilio_service,node_refresh_feed toneIndigo
```

## Components

### User interface

- [Browser UI](https://github.com/sandeepkudupudi07/trapcheck/blob/main/frontend/trapcheck-frontend/src/App.jsx): `frontend/trapcheck-frontend/src/App.jsx`
- [Analysis interface](https://github.com/sandeepkudupudi07/trapcheck/blob/main/frontend/trapcheck-frontend/src/TrapCheck.jsx): `frontend/trapcheck-frontend/src/TrapCheck.jsx`
- [History dashboard](https://github.com/sandeepkudupudi07/trapcheck/blob/main/frontend/trapcheck-frontend/src/History.jsx): `frontend/trapcheck-frontend/src/History.jsx`
- [API client](https://github.com/sandeepkudupudi07/trapcheck/blob/main/frontend/trapcheck-frontend/src/http.js): `frontend/trapcheck-frontend/src/http.js`

### API and security

- [FastAPI application](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/main.py): `backend/main.py`
- [Rate limits](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/rate_limit.py): `backend/rate_limit.py`
- [Safe logging](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/security/zero_log.py): `backend/security/zero_log.py`
- [Message sanitizer](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/security/sanitizer.py): `backend/security/sanitizer.py`
- [Ephemeral processing](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/security/ephemeral.py): `backend/security/ephemeral.py`

### Scam analysis

- [RAG analysis](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/rag_engine.py): `backend/rag_engine.py`
- [Scam patterns](https://github.com/sandeepkudupudi07/trapcheck/blob/main/data/scam_patterns.py): `data/scam_patterns.py`
- [Vector knowledge base](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/rag_engine.py): `backend/rag_engine.py`
- **Ollama model**
- [Threat-feed refresh](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/scheduler/refresh.py): `backend/scheduler/refresh.py`
- [SMS and WhatsApp](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/channels/twilio_handler.py): `backend/channels/twilio_handler.py`

### Accounts and community

- [Account endpoints](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/routes.py): `backend/auth/routes.py`
- [JWT and passwords](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/auth.py): `backend/auth/auth.py`
- [Reset email](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/email_service.py): `backend/auth/email_service.py`
- [Account data models](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/database.py): `backend/auth/database.py`
- [Scam reporting](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/security/anonymous_report.py): `backend/security/anonymous_report.py`
- [Admin review](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/admin_routes.py): `backend/auth/admin_routes.py`
- [Persistent records](https://github.com/sandeepkudupudi07/trapcheck/blob/main/backend/auth/database.py): `backend/auth/database.py`

### Other components

- **User**
- **Twilio**
- **PhishTank feed**

## Connections

- User → Browser UI: uses (evidence: `README.md`)
- Browser UI → Analysis interface: renders (evidence: `frontend/trapcheck-frontend/src/App.jsx`)
- Analysis interface → API client: submits requests (evidence: `frontend/trapcheck-frontend/src/TrapCheck.jsx`)
- History dashboard → API client: requests history (evidence: `frontend/trapcheck-frontend/src/History.jsx`)
- API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Rate limits: applies limits (evidence: `backend/main.py`)
- FastAPI application → Safe logging: installs middleware (evidence: `backend/main.py`)
- FastAPI application → Message sanitizer: sanitizes messages (evidence: `backend/main.py`)
- FastAPI application → RAG analysis: analyzes message (evidence: `README.md`)
- FastAPI application → Account data models: persists history (evidence: `README.md`)
- FastAPI application → Scam reporting: accepts reports (evidence: `backend/main.py`)
- FastAPI application → Threat-feed refresh: starts refresh (evidence: `backend/main.py`)
- RAG analysis → Scam patterns: loads patterns (evidence: `backend/rag_engine.py`)
- RAG analysis → Vector knowledge base: retrieves patterns (evidence: `README.md`)
- RAG analysis → Ollama model: invokes model (evidence: `backend/rag_engine.py`)
- FastAPI application → Ephemeral processing: processes transiently (evidence: `README.md`)
- Account endpoints → JWT and passwords: authenticates users (evidence: `backend/auth/routes.py`)
- JWT and passwords → Account data models: reads and writes (evidence: `backend/auth/auth.py`)
- Account endpoints → Reset email: sends reset email (evidence: `backend/auth/routes.py`)
- Account endpoints → Account data models: reads and writes (evidence: `backend/auth/routes.py`)
- Account data models → Persistent records: stores records (evidence: `backend/auth/database.py`)
- Admin review → Account data models: reviews reports (evidence: `backend/auth/admin_routes.py`)
- Admin review → Vector knowledge base: adds approved patterns (evidence: `README.md`)
- Twilio → SMS and WhatsApp: posts webhooks (evidence: `README.md`)
- SMS and WhatsApp → Message sanitizer: sanitizes input (evidence: `backend/channels/twilio_handler.py`)
- SMS and WhatsApp → RAG analysis: analyzes messages (evidence: `backend/channels/twilio_handler.py`)
- Threat-feed refresh → PhishTank feed: fetches threat feed (evidence: `README.md`)
- Threat-feed refresh → Vector knowledge base: refreshes patterns (evidence: `README.md`)