# ayush-github123/scamsentinalai architecture

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

- Interactive diagram: https://gitdiagram.com/ayush-github123/scamsentinalai
- Repository: https://github.com/ayush-github123/scamsentinalai

## Overview

1. **Top-level shape**
   - This repo is a Python/FastAPI backend for an “agentic honeypot” that receives suspicious messages, classifies them, extracts intelligence, and generates a persona-consistent reply.
   - The codebase is split into an HTTP API layer, a core orchestration layer, analysis/extraction services, an LLM agent layer, and persistence/migration support.

2. **HTTP ingress boundary**
   - `app/main.py` wires the FastAPI application.
   - `app/routes/messages.py` is the main message-processing endpoint, while `app/routes/whatsapp_webhook.py` is the WhatsApp-facing ingress.
   - `app/routes/auth.py` plus `app/middleware.py` enforce request authentication and cross-cutting request handling.
   - `app/schemas/message.py` defines the request/response contract at the API boundary.

3. **Core orchestration pipeline**
   - The main control flow appears to live in `app/core/message_processor.py`.
   - That layer coordinates preprocessing, detection, extraction, state updates, and response selection rather than letting the route handlers contain business logic.
   - `app/core/response_decider.py` and `app/core/state_manager.py` are the decision points that convert analysis results into the next conversational action.

4. **Message analysis subsystem**
   - `app/services/message_preprocessor.py` normalizes incoming text before analysis.
   - `app/services/scam_detector.py` performs rule/pattern-based scam classification and confidence scoring.
   - `app/services/message_scorer.py` likely enriches or combines multiple signals into a final score.
   - `app/services/intelligence_extractor.py` pulls structured entities such as URLs, phone numbers, payment identifiers, and other indicators from the message stream.
   - These services are the main “analysis” boundary between raw user content and structured intelligence.

5. **Conversation and session state**
   - `app/core/session_context.py` and `app/core/state_manager.py` hold the current conversation state, turn count, extracted artifacts, and decision context.
   - The README’s state-machine behavior is reflected here: the system moves through suspicious/engaging/extracting/terminated-style phases based on confidence and collected intelligence.
   - `app/core/encryption.py` suggests sensitive session material or stored artifacts can be protected before persistence or transport.

6. **LLM agent layer**
   - `app/agent/llm_client.py` is the model gateway; it is responsible for calling the external LLM provider and handling fallback behavior.
   - `app/agent/prompts.py` generates the dynamic system/user prompts that enforce persona, guardrails, and state-specific behavior.
   - This layer is intentionally downstream of the rule-based detector/extractor: the LLM is used to craft responses, not to decide whether the message is suspicious.

7. **Domain model and storage**
   - `app/models/enhanced_models.py` contains the persistence/domain entities used by the system.
   - `app/core/database.py` connects the app to its database, and `migrations/` with Alembic config show the schema is versioned rather than ad hoc.
   - The migration history includes table initialization, quota tracking, and API-key removal, which indicates the database is used for operational state and auditability, not just ephemeral session data.

8. **WhatsApp integration boundary**
   - `app/services/whatsapp_listener.py` and `app/services/whatsapp_mcp_integration.py` connect the system to WhatsApp-oriented message sources.
   - `app/services/mcp_agent_connector.py` indicates an adapter layer for MCP-style integration.
   - The nested `wtsp-mcp` project is a separate integration stack:
     - `whatsapp-bridge` is a Go service,
     - `whatsapp-mcp-server` is a Python server,
     - together they act as an external bridge between WhatsApp transport and the agent backend.
   - This is the clearest “edge adapter” in the repo.

9. **Outbound reporting / external side effects**
   - The system is designed to emit extracted intelligence and conversation results to external endpoints once a session terminates or reaches a reporting condition.
   - In architecture terms, that is a distinct outbound integration path separate from the user-facing response path.
   - The repo’s webhook-oriented files and MCP integration imply the system both receives from and reports to external services.

10. **Cross-cutting concerns**
   - `app/logger.py`, `app/exceptions.py`, and `app/middleware.py` provide observability, error handling, and request-level controls.
   - `app/core/config.py` centralizes environment-driven settings such as API keys, model configuration, thresholds, and callback URLs.
   - This means most runtime behavior is configured externally rather than hard-coded.

11. **Runtime and deployment shape**
   - The primary runtime is Python/FastAPI, with Uvicorn as the ASGI server.
   - The presence of `requirements.txt`, Alembic migrations, and REST test files suggests a service-oriented backend that can be exercised over HTTP without a separate frontend.
   - The `tests/` directory and `tests/test.rest` file indicate the repo is designed for API-level verification and manual endpoint testing.

12. **How the data flows end-to-end**
   - Incoming message arrives through the API or WhatsApp webhook.
   - It is authenticated, normalized, scored for scam likelihood, and scanned for structured intelligence.
   - The session/state manager updates conversation context and decides the next conversational state.
   - The prompt builder feeds the current state and missing intelligence into the LLM client.
   - The generated reply is returned to the caller, while session data and extracted intelligence are stored or forwarded to external reporting endpoints when needed.

Main entry points: [`app/core/message_processor.py`](https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/message_processor.py) (Processor), [`app/main.py`](https://github.com/ayush-github123/scamsentinalai/blob/main/app/main.py) (App entry), [`app/routes/messages.py`](https://github.com/ayush-github123/scamsentinalai/blob/main/app/routes/messages.py) (Messages API), [`app/routes/whatsapp_webhook.py`](https://github.com/ayush-github123/scamsentinalai/blob/main/app/routes/whatsapp_webhook.py) (WhatsApp hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_main_app(("App entry<br/>FastAPI app<br/>[main.py]"))
  node_messages_route["Messages API<br/>route<br/>[messages.py]"]
  node_whatsapp_route["WhatsApp hook<br/>route"]
  node_auth_route["Auth API<br/>route<br/>[auth.py]"]
  node_middleware{{"Middleware<br/>request layer<br/>[middleware.py]"}}
  node_message_schema["Message schema<br/>contract<br/>[message.py]"]
end

subgraph group_core["Core Flow"]
  node_processor["Processor<br/>orchestrator"]
  node_response_decider{{"Decider<br/>decision engine"}}
  node_state_manager[("State manager<br/>conversation state<br/>[state_manager.py]")]
  node_session_context[("Session context<br/>session model<br/>[session_context.py]")]
end

subgraph group_analysis["Analysis"]
  node_preprocessor["Preprocessor<br/>text prep"]
  node_scam_detector{{"Scam detector<br/>classifier<br/>[scam_detector.py]"}}
  node_message_scorer(("Scorer<br/>signal fusion<br/>[message_scorer.py]"))
  node_intelligence_extractor["Extractor<br/>entity extraction"]
end

subgraph group_agent["Agent & Integrations"]
  node_llm_client["LLM client<br/>model gateway<br/>[llm_client.py]"]
  node_prompts["Prompt builder<br/>prompting<br/>[prompts.py]"]
  node_whatsapp_listener["Listener<br/>transport adapter"]
  node_whatsapp_mcp["WhatsApp MCP<br/>integration"]
  node_mcp_connector{{"MCP connector<br/>adapter"}}
end

subgraph group_storage["Persistence"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_database[("Database<br/>db connector<br/>[database.py]")]
  node_models[("Domain models<br/>persistence models<br/>[enhanced_models.py]")]
end

node_main_app -->|"wraps"| node_middleware
node_main_app -->|"mounts"| node_messages_route
node_main_app -->|"mounts"| node_whatsapp_route
node_main_app -->|"mounts"| node_auth_route
node_messages_route -->|"uses"| node_message_schema
node_whatsapp_route -.->|"maps to"| node_message_schema
node_auth_route -.->|"checks"| node_config
node_messages_route -->|"delegates"| node_processor
node_whatsapp_route -->|"ingests"| node_whatsapp_listener
node_whatsapp_listener -->|"forwards"| node_processor
node_processor -->|"normalizes"| node_preprocessor
node_processor -->|"classifies"| node_scam_detector
node_processor -->|"scores"| node_message_scorer
node_processor -->|"extracts"| node_intelligence_extractor
node_processor -->|"updates"| node_state_manager
node_processor -->|"decides"| node_response_decider
node_response_decider -->|"reads"| node_session_context
node_state_manager -->|"persists"| node_session_context
node_state_manager -->|"writes"| node_database
node_session_context -->|"feeds"| node_prompts
node_prompts -->|"drives"| node_llm_client
node_llm_client -.->|"returns reply"| node_response_decider
node_processor -->|"stores"| node_models
node_models -->|"persists"| node_database
node_processor -.->|"reports"| node_whatsapp_mcp
node_whatsapp_mcp -->|"adapts"| node_mcp_connector

click node_main_app "https://github.com/ayush-github123/scamsentinalai/blob/main/app/main.py"
click node_messages_route "https://github.com/ayush-github123/scamsentinalai/blob/main/app/routes/messages.py"
click node_whatsapp_route "https://github.com/ayush-github123/scamsentinalai/blob/main/app/routes/whatsapp_webhook.py"
click node_auth_route "https://github.com/ayush-github123/scamsentinalai/blob/main/app/routes/auth.py"
click node_middleware "https://github.com/ayush-github123/scamsentinalai/blob/main/app/middleware.py"
click node_message_schema "https://github.com/ayush-github123/scamsentinalai/blob/main/app/schemas/message.py"
click node_processor "https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/message_processor.py"
click node_response_decider "https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/response_decider.py"
click node_state_manager "https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/state_manager.py"
click node_session_context "https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/session_context.py"
click node_config "https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/config.py"
click node_database "https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/database.py"
click node_models "https://github.com/ayush-github123/scamsentinalai/blob/main/app/models/enhanced_models.py"
click node_preprocessor "https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/message_preprocessor.py"
click node_scam_detector "https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/scam_detector.py"
click node_message_scorer "https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/message_scorer.py"
click node_intelligence_extractor "https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/intelligence_extractor.py"
click node_llm_client "https://github.com/ayush-github123/scamsentinalai/blob/main/app/agent/llm_client.py"
click node_prompts "https://github.com/ayush-github123/scamsentinalai/blob/main/app/agent/prompts.py"
click node_whatsapp_listener "https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/whatsapp_listener.py"
click node_whatsapp_mcp "https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/whatsapp_mcp_integration.py"
click node_mcp_connector "https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/mcp_agent_connector.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_main_app,node_messages_route,node_whatsapp_route,node_auth_route,node_middleware,node_message_schema toneBlue
class node_processor,node_response_decider,node_state_manager,node_session_context toneAmber
class node_preprocessor,node_scam_detector,node_message_scorer,node_intelligence_extractor toneMint
class node_llm_client,node_prompts,node_whatsapp_listener,node_whatsapp_mcp,node_mcp_connector toneRose
class node_config,node_database,node_models toneIndigo
```

## Components

### HTTP API

FastAPI ingress, auth, middleware, and message/webhook routes.

- [App entry](https://github.com/ayush-github123/scamsentinalai/blob/main/app/main.py): FastAPI app · Creates and wires the ASGI application. · `app/main.py`
- [Messages API](https://github.com/ayush-github123/scamsentinalai/blob/main/app/routes/messages.py): route · Primary message-processing endpoint. · `app/routes/messages.py`
- [WhatsApp hook](https://github.com/ayush-github123/scamsentinalai/blob/main/app/routes/whatsapp_webhook.py): route · Webhook ingress from WhatsApp-facing transport. · `app/routes/whatsapp_webhook.py`
- [Auth API](https://github.com/ayush-github123/scamsentinalai/blob/main/app/routes/auth.py): route · Authentication-related endpoint wiring. · `app/routes/auth.py`
- [Middleware](https://github.com/ayush-github123/scamsentinalai/blob/main/app/middleware.py): request layer · Cross-cutting request handling and enforcement. · `app/middleware.py`
- [Message schema](https://github.com/ayush-github123/scamsentinalai/blob/main/app/schemas/message.py): contract · Request and response payload definitions. · `app/schemas/message.py`

### Core Flow

Orchestration, state, decisioning, and shared runtime controls.

- [Processor](https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/message_processor.py): orchestrator · Coordinates preprocessing, detection, extraction, state updates, and reply selection. · `app/core/message_processor.py`
- [Decider](https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/response_decider.py): decision engine · Chooses the next conversational action. · `app/core/response_decider.py`
- [State manager](https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/state_manager.py): conversation state · Tracks phase, turn context, and decision state. · `app/core/state_manager.py`
- [Session context](https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/session_context.py): session model · Holds per-conversation runtime context and artifacts. · `app/core/session_context.py`

### Analysis

Preprocessing, scoring, scam detection, and intelligence extraction.

- [Preprocessor](https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/message_preprocessor.py): text prep · Normalizes incoming messages before analysis. · `app/services/message_preprocessor.py`
- [Scam detector](https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/scam_detector.py): classifier · Rule and pattern-based suspiciousness scoring. · `app/services/scam_detector.py`
- [Scorer](https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/message_scorer.py): signal fusion · Combines signals into a final score. · `app/services/message_scorer.py`
- [Extractor](https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/intelligence_extractor.py): entity extraction · Pulls URLs, phone numbers, payment IDs, and indicators. · `app/services/intelligence_extractor.py`

### Agent & Integrations

LLM prompting and external transport/adapters.

- [LLM client](https://github.com/ayush-github123/scamsentinalai/blob/main/app/agent/llm_client.py): model gateway · Calls the external language model and handles fallback behavior. · `app/agent/llm_client.py`
- [Prompt builder](https://github.com/ayush-github123/scamsentinalai/blob/main/app/agent/prompts.py): prompting · Builds persona and state-aware prompts. · `app/agent/prompts.py`
- [Listener](https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/whatsapp_listener.py): transport adapter · Listens for WhatsApp-oriented message sources. · `app/services/whatsapp_listener.py`
- [WhatsApp MCP](https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/whatsapp_mcp_integration.py): integration · Connects WhatsApp flows to MCP-style integration. · `app/services/whatsapp_mcp_integration.py`
- [MCP connector](https://github.com/ayush-github123/scamsentinalai/blob/main/app/services/mcp_agent_connector.py): adapter · Adapter for MCP agent integration. · `app/services/mcp_agent_connector.py`

### Persistence

Database models, migrations, and configuration/observability support.

- [Config](https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/config.py): settings · Environment-driven thresholds, keys, and callbacks. · `app/core/config.py`
- [Database](https://github.com/ayush-github123/scamsentinalai/blob/main/app/core/database.py): db connector · Database connection and session wiring. · `app/core/database.py`
- [Domain models](https://github.com/ayush-github123/scamsentinalai/blob/main/app/models/enhanced_models.py): persistence models · Stored entities and operational records. · `app/models/enhanced_models.py`

## Connections

- App entry → Middleware: wraps · Registers request middleware around the API.
- App entry → Messages API: mounts · Exposes the main message endpoint.
- App entry → WhatsApp hook: mounts · Exposes WhatsApp webhook ingress.
- App entry → Auth API: mounts · Exposes auth-related routes.
- Messages API → Message schema: uses · Validates request and response payloads.
- WhatsApp hook → Message schema: maps to · Converts webhook data into API message shapes.
- Auth API → Config: checks · Uses configured auth values and secrets.
- Messages API → Processor: delegates · Hands business logic to the orchestrator.
- WhatsApp hook → Listener: ingests · Receives inbound transport messages.
- Listener → Processor: forwards · Routes inbound content into the core pipeline.
- Processor → Preprocessor: normalizes · Cleans and standardizes incoming text.
- Processor → Scam detector: classifies · Evaluates suspiciousness.
- Processor → Scorer: scores · Combines scoring signals.
- Processor → Extractor: extracts · Pulls structured indicators from content.
- Processor → State manager: updates · Advances conversation phase and decision state.
- Processor → Decider: decides · Selects the next action based on analysis and state.
- Decider → Session context: reads · Uses current conversation context.
- State manager → Session context: persists · Stores and refreshes session context.
- State manager → Database: writes · Persists operational conversation state.
- Session context → Prompt builder: feeds · Provides state and missing intel to prompts.
- Prompt builder → LLM client: drives · Supplies the generated prompt for response creation.
- LLM client → Decider: returns reply · Supplies generated response candidates or fallback output.
- Processor → Domain models: stores · Records extracted artifacts and session metadata.
- Domain models → Database: persists · Stored through the database layer.
- Processor → WhatsApp MCP: reports · Sends terminal or reporting outcomes outward.
- WhatsApp MCP → MCP connector: adapts · Bridges to MCP agent integration.