# ari-111/honeypot architecture

> Architecture diagram of the GitHub repository ari-111/honeypot, 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/ari-111/honeypot
- Repository: https://github.com/ari-111/honeypot

## Overview

This is a FastAPI scam-detection honeypot: an incoming message is validated and rate-limited, analyzed for scam intent, answered in a selected persona when suspicious, and mined for intelligence; qualifying sessions are reported to GUVI. The graph follows relationships visible in excerpts, the SOURCE INDEX, or README. Engagement strategy and several documented API capabilities are included, but unsampled implementation details and their connections are not inferred.

Main entry points: [`api/routes.py`](https://github.com/ari-111/honeypot/blob/main/api/routes.py) (Honeypot endpoints), [`main.py`](https://github.com/ari-111/honeypot/blob/main/main.py) (FastAPI app), [`core/agent_manager.py`](https://github.com/ari-111/honeypot/blob/main/core/agent_manager.py) (Agent manager), [`utils/callback_handler.py`](https://github.com/ari-111/honeypot/blob/main/utils/callback_handler.py) (GUVI callback handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and sessions"]
  node_app["FastAPI app<br/>[main.py]"]
  node_routes["Honeypot endpoints<br/>[routes.py]"]
  node_middleware["Rate limiter<br/>[middleware.py]"]
  node_schemas["Request and response models<br/>[session.py]"]
  node_session["Session state<br/>[routes.py]"]
end

subgraph group_detection["Detection and intelligence"]
  node_detector["Scam detector<br/>[scam_detector.py]"]
  node_extractor["Intelligence extractor"]
  node_validators["Data validators<br/>[validators.py]"]
end

subgraph group_agent["Agent conversation"]
  node_agent["Agent manager<br/>[agent_manager.py]"]
  node_personas["Persona selection<br/>[persona_engine.py]"]
  node_persona_data["Persona profiles"]
  node_strategy["Engagement strategy"]
end

subgraph group_integrations["Reporting and configuration"]
  node_openai["OpenAI service"]
  node_callback["GUVI callback handler"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_caller(("API caller"))
node_guvi["GUVI evaluation endpoint"]

node_caller -->|"sends requests"| node_app
node_app -->|"registers routes"| node_routes
node_app -->|"installs limiter"| node_middleware
node_app -->|"validates fallback requests"| node_schemas
node_routes -->|"uses API models"| node_schemas
node_routes -->|"manages sessions"| node_session
node_routes -->|"detects scam intent"| node_detector
node_routes -->|"generates replies"| node_agent
node_routes -->|"extracts intelligence"| node_extractor
node_routes -->|"selects persona"| node_personas
node_personas -->|"loads profiles"| node_persona_data
node_agent -->|"requests completions"| node_openai
node_agent -->|"reads model settings"| node_config
node_middleware -->|"reads rate limits"| node_config
node_routes -->|"triggers reports"| node_callback
node_callback -->|"posts findings"| node_guvi
node_callback -->|"reads callback settings"| node_config
node_strategy -.->|"guides conversation"| node_agent
node_extractor -.->|"validates extracted data"| node_validators

click node_app "https://github.com/ari-111/honeypot/blob/main/main.py"
click node_routes "https://github.com/ari-111/honeypot/blob/main/api/routes.py"
click node_middleware "https://github.com/ari-111/honeypot/blob/main/api/middleware.py"
click node_schemas "https://github.com/ari-111/honeypot/blob/main/models/session.py"
click node_session "https://github.com/ari-111/honeypot/blob/main/api/routes.py"
click node_detector "https://github.com/ari-111/honeypot/blob/main/core/scam_detector.py"
click node_extractor "https://github.com/ari-111/honeypot/blob/main/core/intelligence_extractor.py"
click node_validators "https://github.com/ari-111/honeypot/blob/main/utils/validators.py"
click node_agent "https://github.com/ari-111/honeypot/blob/main/core/agent_manager.py"
click node_personas "https://github.com/ari-111/honeypot/blob/main/core/persona_engine.py"
click node_persona_data "https://github.com/ari-111/honeypot/tree/main/personas"
click node_strategy "https://github.com/ari-111/honeypot/blob/main/core/engagement_strategy.py"
click node_callback "https://github.com/ari-111/honeypot/blob/main/utils/callback_handler.py"
click node_config "https://github.com/ari-111/honeypot/blob/main/config.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_app,node_routes,node_middleware,node_schemas,node_session toneBlue
class node_detector,node_extractor,node_validators toneAmber
class node_agent,node_personas,node_persona_data,node_strategy,node_caller toneMint
class node_openai,node_callback,node_config toneRose
class node_guvi toneIndigo
```

## Components

### API and sessions

- [FastAPI app](https://github.com/ari-111/honeypot/blob/main/main.py): `main.py`
- [Honeypot endpoints](https://github.com/ari-111/honeypot/blob/main/api/routes.py): `api/routes.py`
- [Rate limiter](https://github.com/ari-111/honeypot/blob/main/api/middleware.py): `api/middleware.py`
- [Request and response models](https://github.com/ari-111/honeypot/blob/main/models/session.py): `models/session.py`
- [Session state](https://github.com/ari-111/honeypot/blob/main/api/routes.py): `api/routes.py`

### Detection and intelligence

- [Scam detector](https://github.com/ari-111/honeypot/blob/main/core/scam_detector.py): `core/scam_detector.py`
- [Intelligence extractor](https://github.com/ari-111/honeypot/blob/main/core/intelligence_extractor.py): `core/intelligence_extractor.py`
- [Data validators](https://github.com/ari-111/honeypot/blob/main/utils/validators.py): `utils/validators.py`

### Agent conversation

- [Agent manager](https://github.com/ari-111/honeypot/blob/main/core/agent_manager.py): `core/agent_manager.py`
- [Persona selection](https://github.com/ari-111/honeypot/blob/main/core/persona_engine.py): `core/persona_engine.py`
- [Persona profiles](https://github.com/ari-111/honeypot/tree/main/personas): `personas`
- [Engagement strategy](https://github.com/ari-111/honeypot/blob/main/core/engagement_strategy.py): `core/engagement_strategy.py`

### Reporting and configuration

- **OpenAI service**
- [GUVI callback handler](https://github.com/ari-111/honeypot/blob/main/utils/callback_handler.py): `utils/callback_handler.py`
- [Runtime configuration](https://github.com/ari-111/honeypot/blob/main/config.py): `config.py`

### Other components

- **API caller**
- **GUVI evaluation endpoint**

## Connections

- API caller → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Honeypot endpoints: registers routes (evidence: `main.py`)
- FastAPI app → Rate limiter: installs limiter (evidence: `main.py`)
- FastAPI app → Request and response models: validates fallback requests (evidence: `main.py`)
- Honeypot endpoints → Request and response models: uses API models (evidence: `api/routes.py`)
- Honeypot endpoints → Session state: manages sessions (evidence: `api/routes.py`)
- Honeypot endpoints → Scam detector: detects scam intent (evidence: `api/routes.py`)
- Honeypot endpoints → Agent manager: generates replies (evidence: `api/routes.py`)
- Honeypot endpoints → Intelligence extractor: extracts intelligence (evidence: `api/routes.py`)
- Honeypot endpoints → Persona selection: selects persona (evidence: `api/routes.py`)
- Persona selection → Persona profiles: loads profiles (evidence: `core/persona_engine.py`)
- Agent manager → OpenAI service: requests completions (evidence: `core/agent_manager.py`)
- Agent manager → Runtime configuration: reads model settings (evidence: `core/agent_manager.py`)
- Rate limiter → Runtime configuration: reads rate limits (evidence: `api/middleware.py`)
- Honeypot endpoints → GUVI callback handler: triggers reports (evidence: `api/routes.py`)
- GUVI callback handler → GUVI evaluation endpoint: posts findings (evidence: `utils/callback_handler.py`)
- GUVI callback handler → Runtime configuration: reads callback settings (evidence: `utils/callback_handler.py`)
- Engagement strategy → Agent manager: guides conversation
- Intelligence extractor → Data validators: validates extracted data
