# chirag0071/saffronai---agentic-honey-pot-for-scam-detection architecture

> Architecture diagram of the GitHub repository chirag0071/saffronai---agentic-honey-pot-for-scam-detection, 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/chirag0071/saffronai---agentic-honey-pot-for-scam-detection
- Repository: https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection

## Overview

SAFFRON AI is a FastAPI scam-honeypot backend: GUVI or another caller submits one message per session, and the API retrieves conversation state, generates a human-like reply, extracts scam intelligence, and sends a final GUVI report when the session meets its completion threshold. The runtime includes engagement, forensic extraction, attack-flow and risk analysis, and callback reporting. The session store is in-memory. The README documents these product capabilities; the graph’s implementation-level links are limited to the provided excerpts and documented flow.

Main entry points: [`backend/app/core/intelligence.py`](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py) (Intelligence extractor), [`backend/app/api/main.py`](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/api/main.py) (Message API), [`backend/app/models/models.py`](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/models/models.py) (Session state), [`backend/app/core/session_manager.py`](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/session_manager.py) (Session manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["API and sessions"]
  node_api["Message API<br/>[main.py]"]
  node_session_manager["Session manager<br/>[session_manager.py]"]
  node_session_model["Session state<br/>[models.py]"]
end

subgraph group_engagement["Scammer engagement"]
  node_agent["Honeypot agent<br/>[agent.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_analysis["Intelligence analysis"]
  node_extractor["Intelligence extractor<br/>[intelligence.py]"]
  node_intel_records["Extracted indicators<br/>[intelligence.py]"]
  node_scam_classification["Scam classification<br/>[intelligence.py]"]
  node_confidence["Confidence scoring<br/>[intelligence.py]"]
  node_attack_flow["Attack reconstruction<br/>[intelligence.py]"]
  node_risk["Risk estimation<br/>[intelligence.py]"]
  node_completion["Completion threshold<br/>[intelligence.py]"]
end

subgraph group_reporting["Result reporting"]
  node_callback["GUVI callback client<br/>[guvi_client.py]"]
end

node_caller(("Message caller"))
node_guvi["GUVI evaluator"]

node_caller -->|"submits message"| node_api
node_api -->|"gets session"| node_session_manager
node_session_manager -->|"creates state"| node_session_model
node_api -->|"appends messages"| node_session_model
node_api -->|"requests reply"| node_agent
node_agent -->|"generates reply"| node_llm
node_api -->|"extracts intelligence"| node_extractor
node_extractor -->|"reads and updates"| node_session_model
node_extractor -->|"requests extraction"| node_llm
node_extractor -->|"extracts indicators"| node_intel_records
node_extractor -->|"classifies scam"| node_scam_classification
node_extractor -->|"scores confidence"| node_confidence
node_extractor -->|"infers attack flow"| node_attack_flow
node_extractor -->|"calculates risk"| node_risk
node_extractor -->|"checks threshold"| node_completion
node_api -->|"sends final result"| node_callback
node_callback -->|"posts report"| node_guvi

click node_api "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/api/main.py"
click node_session_manager "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/session_manager.py"
click node_session_model "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/models/models.py"
click node_agent "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/agent.py"
click node_llm "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/services/llm_client.py"
click node_extractor "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py"
click node_intel_records "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py"
click node_scam_classification "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py"
click node_confidence "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py"
click node_attack_flow "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py"
click node_risk "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py"
click node_completion "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py"
click node_callback "https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/services/guvi_client.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_api,node_session_manager,node_session_model toneBlue
class node_agent,node_llm toneAmber
class node_extractor,node_intel_records,node_scam_classification,node_confidence,node_attack_flow,node_risk,node_completion toneMint
class node_callback toneRose
class node_caller,node_guvi toneIndigo
```

## Components

### API and sessions

- [Message API](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/api/main.py): `backend/app/api/main.py`
- [Session manager](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/session_manager.py): `backend/app/core/session_manager.py`
- [Session state](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/models/models.py): `backend/app/models/models.py`

### Scammer engagement

- [Honeypot agent](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/agent.py): `backend/app/core/agent.py`
- [LLM client](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/services/llm_client.py): `backend/app/services/llm_client.py`

### Intelligence analysis

- [Intelligence extractor](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py): `backend/app/core/intelligence.py`
- [Extracted indicators](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py): `backend/app/core/intelligence.py`
- [Scam classification](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py): `backend/app/core/intelligence.py`
- [Confidence scoring](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py): `backend/app/core/intelligence.py`
- [Attack reconstruction](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py): `backend/app/core/intelligence.py`
- [Risk estimation](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py): `backend/app/core/intelligence.py`
- [Completion threshold](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/core/intelligence.py): `backend/app/core/intelligence.py`

### Result reporting

- [GUVI callback client](https://github.com/chirag0071/saffronai---agentic-honey-pot-for-scam-detection/blob/main/backend/app/services/guvi_client.py): `backend/app/services/guvi_client.py`

### Other components

- **Message caller**
- **GUVI evaluator**

## Connections

- Message caller → Message API: submits message (evidence: `README.md`)
- Message API → Session manager: gets session (evidence: `backend/app/api/main.py`)
- Session manager → Session state: creates state (evidence: `backend/app/core/session_manager.py`)
- Message API → Session state: appends messages (evidence: `backend/app/api/main.py`)
- Message API → Honeypot agent: requests reply (evidence: `backend/app/api/main.py`)
- Honeypot agent → LLM client: generates reply (evidence: `backend/app/core/agent.py`)
- Message API → Intelligence extractor: extracts intelligence (evidence: `backend/app/api/main.py`)
- Intelligence extractor → Session state: reads and updates (evidence: `backend/app/core/intelligence.py`)
- Intelligence extractor → LLM client: requests extraction (evidence: `backend/app/core/intelligence.py`)
- Intelligence extractor → Extracted indicators: extracts indicators (evidence: `backend/app/core/intelligence.py`)
- Intelligence extractor → Scam classification: classifies scam (evidence: `backend/app/core/intelligence.py`)
- Intelligence extractor → Confidence scoring: scores confidence (evidence: `backend/app/core/intelligence.py`)
- Intelligence extractor → Attack reconstruction: infers attack flow (evidence: `backend/app/core/intelligence.py`)
- Intelligence extractor → Risk estimation: calculates risk (evidence: `backend/app/core/intelligence.py`)
- Intelligence extractor → Completion threshold: checks threshold (evidence: `backend/app/core/intelligence.py`)
- Message API → GUVI callback client: sends final result (evidence: `backend/app/api/main.py`)
- GUVI callback client → GUVI evaluator: posts report (evidence: `backend/app/services/guvi_client.py`)
