# the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked architecture

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

- Interactive diagram: https://gitdiagram.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked
- Repository: https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked

## Overview

Honey, We Trapped the Scammers is a FastAPI honeypot that engages suspected financial scammers and reports the intelligence it gathers. An incoming message enters the API, is serialized with its session’s other turns, normalized and translated, and checked for intelligence. The orchestrator then coordinates Analyst classification, Strategist planning, and Operator reply generation; session state and harvested data persist across turns. The service also exposes per-turn transparency and sends a final intelligence callback. Edges reflect shown source references and README claims; several implementation details are unsampled, so uncertain links are omitted.

Main entry points: [`src/main.py`](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/main.py) (Honeypot API), [`src/orchestrator.py`](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/orchestrator.py) (Turn orchestrator), [`src/llm_client.py`](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/llm_client.py) (LLM provider client), [`src/agents/analyst.py`](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/agents/analyst.py) (Analyst agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and sessions"]
  node_api["Honeypot API<br/>[main.py]"]
  node_lock["Session lock<br/>[session_lock.py]"]
end

subgraph group_processing["Message processing"]
  node_translation["Translation<br/>[translator.py]"]
  node_extraction["Intelligence extraction<br/>[extractor.py]"]
  node_llm["LLM provider client<br/>[llm_client.py]"]
end

subgraph group_agents["Engagement agents"]
  node_orchestrator["Turn orchestrator<br/>[orchestrator.py]"]
  node_analyst["Analyst agent<br/>[analyst.py]"]
  node_strategist["Strategist agent<br/>[strategist.py]"]
  node_operator["Operator agent<br/>[operator.py]"]
  node_personas["Persona pool<br/>[persona_pool.py]"]
  node_latency["Reply latency<br/>[latency.py]"]
end

subgraph group_state["Session intelligence"]
  node_session[("Session persistence<br/>[models.py]")]
end

subgraph group_reporting["Reporting and integrations"]
  node_transparency["Transparency stream<br/>[transparency.py]"]
  node_callback["Final intelligence callback<br/>[callback.py]"]
end

node_scammer(("Scammer"))
node_guvi["GUVI endpoints"]

node_scammer -->|"sends message"| node_api
node_api -->|"serializes turns"| node_lock
node_api -->|"loads and updates"| node_session
node_api -->|"translates text"| node_translation
node_api -->|"extracts intelligence"| node_extraction
node_api -->|"processes turn"| node_orchestrator
node_orchestrator -->|"classifies message"| node_analyst
node_orchestrator -->|"plans tactic"| node_strategist
node_orchestrator -->|"generates reply"| node_operator
node_orchestrator -->|"selects persona"| node_personas
node_orchestrator -->|"calculates delay"| node_latency
node_analyst -->|"requests analysis"| node_llm
node_strategist -->|"requests strategy"| node_llm
node_operator -->|"requests reply"| node_llm
node_api -->|"serves stream"| node_transparency
node_orchestrator -->|"builds turn event"| node_transparency
node_api -->|"dispatches final result"| node_callback
node_callback -->|"posts intelligence"| node_guvi

click node_api "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/main.py"
click node_lock "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/session_lock.py"
click node_translation "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/translator.py"
click node_extraction "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/extractor.py"
click node_orchestrator "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/orchestrator.py"
click node_analyst "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/agents/analyst.py"
click node_strategist "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/agents/strategist.py"
click node_operator "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/agents/operator.py"
click node_personas "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/personas/persona_pool.py"
click node_latency "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/tools/latency.py"
click node_llm "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/llm_client.py"
click node_session "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/models.py"
click node_transparency "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/transparency.py"
click node_callback "https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/callback.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_lock toneBlue
class node_translation,node_extraction,node_llm toneAmber
class node_orchestrator,node_analyst,node_strategist,node_operator,node_personas,node_latency toneMint
class node_session toneRose
class node_transparency,node_callback,node_scammer,node_guvi toneIndigo
```

## Components

### API and sessions

- [Honeypot API](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/main.py): `src/main.py`
- [Session lock](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/session_lock.py): `src/session_lock.py`

### Message processing

- [Translation](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/translator.py): `src/translator.py`
- [Intelligence extraction](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/extractor.py): `src/extractor.py`
- [LLM provider client](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/llm_client.py): `src/llm_client.py`

### Engagement agents

- [Turn orchestrator](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/orchestrator.py): `src/orchestrator.py`
- [Analyst agent](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/agents/analyst.py): `src/agents/analyst.py`
- [Strategist agent](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/agents/strategist.py): `src/agents/strategist.py`
- [Operator agent](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/agents/operator.py): `src/agents/operator.py`
- [Persona pool](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/personas/persona_pool.py): `src/personas/persona_pool.py`
- [Reply latency](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/tools/latency.py): `src/tools/latency.py`

### Session intelligence

- [Session persistence](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/models.py): `src/models.py`

### Reporting and integrations

- [Transparency stream](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/transparency.py): `src/transparency.py`
- [Final intelligence callback](https://github.com/the-eco-guy/honey_we_trapped_the_scammers_microsoft_ai_unlocked/blob/main/src/callback.py): `src/callback.py`

### Other components

- **Scammer**
- **GUVI endpoints**

## Connections

- Scammer → Honeypot API: sends message (evidence: `README.md`)
- Honeypot API → Session lock: serializes turns (evidence: `src/main.py`)
- Honeypot API → Session persistence: loads and updates (evidence: `src/main.py`)
- Honeypot API → Translation: translates text (evidence: `src/main.py`)
- Honeypot API → Intelligence extraction: extracts intelligence (evidence: `src/main.py`)
- Honeypot API → Turn orchestrator: processes turn (evidence: `src/main.py`)
- Turn orchestrator → Analyst agent: classifies message (evidence: `src/orchestrator.py`)
- Turn orchestrator → Strategist agent: plans tactic (evidence: `src/orchestrator.py`)
- Turn orchestrator → Operator agent: generates reply (evidence: `src/orchestrator.py`)
- Turn orchestrator → Persona pool: selects persona (evidence: `src/orchestrator.py`)
- Turn orchestrator → Reply latency: calculates delay (evidence: `src/orchestrator.py`)
- Analyst agent → LLM provider client: requests analysis (evidence: `src/agents/analyst.py`)
- Strategist agent → LLM provider client: requests strategy (evidence: `src/agents/strategist.py`)
- Operator agent → LLM provider client: requests reply (evidence: `src/agents/operator.py`)
- Honeypot API → Transparency stream: serves stream (evidence: `src/main.py`)
- Turn orchestrator → Transparency stream: builds turn event (evidence: `src/orchestrator.py`)
- Honeypot API → Final intelligence callback: dispatches final result (evidence: `README.md`)
- Final intelligence callback → GUVI endpoints: posts intelligence (evidence: `src/callback.py`)
