# utkarshkant/scamguardai architecture

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

- Interactive diagram: https://gitdiagram.com/utkarshkant/scamguardai
- Repository: https://github.com/utkarshkant/scamguardai

## Overview

ScamGuardAI is a message-level scam detector with both a terminal runner and a Streamlit interface. A user submits a message; the interface calls the detector, which builds a strategy-specific prompt, sends it through the LLM executor/client to Google Gemini, and parses the response into a label, reasoning, intent, and risk factors for display or terminal output. The README documents both entry points and Gemini API-key setup. The graph follows the sampled source; unsampled behavior is not inferred beyond documented capabilities.

Main entry points: [`pipeline/scam_detector/detector.py`](https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/detector.py) (Scam Detector), [`llm/prompts.py`](https://github.com/utkarshkant/scamguardai/blob/main/llm/prompts.py) (Prompt Generator), [`llm/client.py`](https://github.com/utkarshkant/scamguardai/blob/main/llm/client.py) (Gemini Client), [`main.py`](https://github.com/utkarshkant/scamguardai/blob/main/main.py) (Terminal Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["Terminal Runner<br/>[main.py]"]
  node_ui["Streamlit Interface<br/>[app.py]"]
end

subgraph group_detection["Detection Pipeline"]
  node_detector["Scam Detector<br/>[detector.py]"]
  node_builder["Prompt Builder<br/>[builder.py]"]
  node_parser["Output Parser<br/>[parser.py]"]
  node_executor["LLM Executor<br/>[executor.py]"]
end

subgraph group_llm["LLM Integration"]
  node_prompts["Prompt Generator<br/>[prompts.py]"]
  node_prompt_asset["ReAct Prompt<br/>[react.md]"]
  node_client["Gemini Client<br/>[client.py]"]
end

subgraph group_shared["Configuration and Helpers"]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_utils["Shared Helpers<br/>[utils.py]"]
end

node_user(("Message Submitter"))
node_gemini["Google Gemini"]

node_user -->|"enters message"| node_cli
node_user -->|"enters message"| node_ui
node_cli -->|"calls detection"| node_detector
node_ui -->|"calls detection"| node_detector
node_detector -->|"builds prompt"| node_builder
node_builder -->|"generates prompt"| node_prompts
node_prompts -->|"loads template"| node_prompt_asset
node_prompts -->|"reads file"| node_utils
node_detector -->|"executes prompt"| node_executor
node_executor -->|"calls model"| node_client
node_client -->|"reads settings"| node_config
node_client -->|"sends prompt"| node_gemini
node_detector -->|"parses response"| node_parser
node_parser -->|"extracts JSON"| node_utils
node_detector -->|"returns result"| node_cli
node_detector -->|"returns result"| node_ui

click node_cli "https://github.com/utkarshkant/scamguardai/blob/main/main.py"
click node_ui "https://github.com/utkarshkant/scamguardai/blob/main/streamlit/app.py"
click node_detector "https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/detector.py"
click node_builder "https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/builder.py"
click node_parser "https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/parser.py"
click node_executor "https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/executor.py"
click node_prompts "https://github.com/utkarshkant/scamguardai/blob/main/llm/prompts.py"
click node_prompt_asset "https://github.com/utkarshkant/scamguardai/blob/main/llm/prompt_library/react.md"
click node_client "https://github.com/utkarshkant/scamguardai/blob/main/llm/client.py"
click node_config "https://github.com/utkarshkant/scamguardai/blob/main/config.py"
click node_utils "https://github.com/utkarshkant/scamguardai/blob/main/utils.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_cli,node_ui toneBlue
class node_detector,node_builder,node_parser,node_executor toneAmber
class node_prompts,node_prompt_asset,node_client toneMint
class node_config,node_utils toneRose
class node_user,node_gemini toneIndigo
```

## Components

### User Interfaces

- [Terminal Runner](https://github.com/utkarshkant/scamguardai/blob/main/main.py): `main.py`
- [Streamlit Interface](https://github.com/utkarshkant/scamguardai/blob/main/streamlit/app.py): `streamlit/app.py`

### Detection Pipeline

- [Scam Detector](https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/detector.py): `pipeline/scam_detector/detector.py`
- [Prompt Builder](https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/builder.py): `pipeline/scam_detector/builder.py`
- [Output Parser](https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/parser.py): `pipeline/scam_detector/parser.py`
- [LLM Executor](https://github.com/utkarshkant/scamguardai/blob/main/pipeline/scam_detector/executor.py): `pipeline/scam_detector/executor.py`

### LLM Integration

- [Prompt Generator](https://github.com/utkarshkant/scamguardai/blob/main/llm/prompts.py): `llm/prompts.py`
- [ReAct Prompt](https://github.com/utkarshkant/scamguardai/blob/main/llm/prompt_library/react.md): `llm/prompt_library/react.md`
- [Gemini Client](https://github.com/utkarshkant/scamguardai/blob/main/llm/client.py): `llm/client.py`

### Configuration and Helpers

- [Runtime Configuration](https://github.com/utkarshkant/scamguardai/blob/main/config.py): `config.py`
- [Shared Helpers](https://github.com/utkarshkant/scamguardai/blob/main/utils.py): `utils.py`

### Other components

- **Message Submitter**
- **Google Gemini**

## Connections

- Message Submitter → Terminal Runner: enters message (evidence: `main.py`)
- Message Submitter → Streamlit Interface: enters message (evidence: `streamlit/app.py`)
- Terminal Runner → Scam Detector: calls detection (evidence: `main.py`)
- Streamlit Interface → Scam Detector: calls detection (evidence: `streamlit/app.py`)
- Scam Detector → Prompt Builder: builds prompt (evidence: `pipeline/scam_detector/detector.py`)
- Prompt Builder → Prompt Generator: generates prompt (evidence: `pipeline/scam_detector/builder.py`)
- Prompt Generator → ReAct Prompt: loads template (evidence: `llm/prompts.py`)
- Prompt Generator → Shared Helpers: reads file (evidence: `llm/prompts.py`)
- Scam Detector → LLM Executor: executes prompt (evidence: `pipeline/scam_detector/detector.py`)
- LLM Executor → Gemini Client: calls model (evidence: `pipeline/scam_detector/executor.py`)
- Gemini Client → Runtime Configuration: reads settings (evidence: `llm/client.py`)
- Gemini Client → Google Gemini: sends prompt (evidence: `llm/client.py`)
- Scam Detector → Output Parser: parses response (evidence: `pipeline/scam_detector/detector.py`)
- Output Parser → Shared Helpers: extracts JSON (evidence: `pipeline/scam_detector/parser.py`)
- Scam Detector → Terminal Runner: returns result (evidence: `main.py`)
- Scam Detector → Streamlit Interface: returns result (evidence: `streamlit/app.py`)
