ayush-github123/scamsentinalai

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.