# Topic 1: High-Level System Architecture

**Audit Date**: 2026-02-01
**Auditor**: Agent Antigravity (Senior Architect)
**Scope**: Folder-Level Structure & Core Design Patterns

---

## 1. Architectural Overview
The **Sentinel Scam Honeypot** is designed as a **Modular Agentic Monolith** built on **FastAPI**. It follows a **Layered Architecture** pattern, separating the API Ingress, Agentic Logic, Intelligence Processing, and Persistence layers.

### **Core Design Pattern: The OODA Loop**
The system is not a linear chatbot. It implements a **Cybernetic OODA Loop** (Observe, Orient, Decide, Act) managed by the central **Orchestrator**.
1.  **Ingress (`app/api`)**: Receives raw message + metadata.
2.  **Observe (`app/agents/scam_detector`)**: Classifies intent and extracts entities.
3.  **Orient (`app/intelligence`)**: Enriches data with Threat Intel, GraphDB, and Risk Scores.
4.  **Decide (`app/agents/adaptive_strategy`)**: Selects the optimal Persona and Engagement Phase.
5.  **Act (`app/agents/persona_engine`)**: Generates the response or executes enforcement actions.

---

## 2. Folder-by-Folder Responsibilities (Strict Verification)

### **A. Ingress & Interface Layer**
| Folder | Responsibility | Status |
| :--- | :--- | :--- |
| **`app/api`** | REST API Routes (`routes.py`) and Pydantic Schemas (`schemas.py`). Enforces `x-api-key` auth. | **REAL** |
| **`app/templates`** | HTML/Jinja2 templates for the Admin Dashboard. | **REAL** (UI) |
| **`app/middleware`** | Rate limiting (`rate_limiter.py`) and CORS configuration. | **REAL** |
| **`web`** | Static assets (CSS/JS) for the dashboard. | **REAL** |

### **B. Agentic Core (The "Brain")**
| Folder | Responsibility | Status |
| :--- | :--- | :--- |
| **`app/agents`** | Contains the **Orchestrator** (Controller) and specialized sub-agents: <br>• **Detector**: Identifies scams.<br>• **Persona**: Manages roles/styles.<br>• **Extractor**: Pulls PII/IOCs.<br>• **Manager**: Handles session state. | **REAL** |
| **`app/core`** | Low-level infrastructure:<br>• **`llm_client.py`**: Switchboard for Groq/OpenAI.<br>• **`model_registry.py`**: Model definitions & limits.<br>• **`prompts.py`**: Jinja2 prompt templates. | **REAL** |

### **C. Intelligence Layer (The "Analyst")**
| Folder | Responsibility | Status |
| :--- | :--- | :--- |
| **`app/intelligence`** | Advanced processing modules:<br>• **`threat_engine.py`**: Clusters campaigns.<br>• **`telemetry.py`**: Tracks IP/Geo.<br>• **`enrichment_service.py`**: Validates entities (Mock/Regex/Live).<br>• **`mitre_mapper.py`**: TTP Mapping. | **HYBRID**<br>(Real Logic, mocked external feeds) |

### **D. Persistence & Tools**
| Folder | Responsibility | Status |
| :--- | :--- | :--- |
| **`app/database`** | SQLAlchemy/AioSQLite ORM.<br>• **`db.py`**: Connection & Fallback logic.<br>• **`models.py`**: Schema definitions. | **REAL** |
| **`app/utils`** | Shared utilities:<br>• **`callback_client.py`**: GUVI mandatory reporting.<br>• **`guvi_handler.py`**: Protocol translation. | **REAL** |
| **`app/decoys`** | **`fake_endpoints.py`**: Generates Honeytokens (Fake Bank Logins) to trap scammers. | **REAL** (Trap) |
| **`app/enforcement`** | **`police_api.py`**: Simulates filing reports to Cyber Cell. | **SIMULATED** |

---

## 3. Truth Table: Real vs. Simulated Components

| Component | Status | Verification Evidence |
| :--- | :--- | :--- |
| **LLM Reasoning** | **REAL** | `app/core/llm_client.py` calls Groq API directly. |
| **Database Storage** | **REAL** | `app/database/db.py` creates `honeypot.db` file. |
| **Scam Detection** | **REAL** | `scam_detector.py` uses Hybrid (Regex + LLM) analysis. |
| **Police Reporting** | **SIMULATED** | `police_api.py` returns mocked "Request IDs". |
| **Bank/UPI Freezing** | **SIMULATED** | `bank_api.py` returns mocked "Freeze Status". |
| **Threat Feeds** | **SIMULATED** | `threat_feeds.py` generates realistic dummy data for dashboard. |
| **Honeytokens** | **REAL** | `honeytokens.py` generates valid-looking fake creds. |
| **GUVI Callback** | **REAL** | `callback_client.py` sends HTTP POST to valid endpoint. |

---

## 4. Special Analysis Sections

### **A. Model Strategy & Switching**
-   **Primary**: `llama-3.3-70b-versatile` (Intelligence).
-   **High-Volume**: `llama-4-scout-17b` (Speed/Switchboard Fallback).
-   **High-Context**: `moonshotai/kimi-k2-instruct` (Context > 100k).
-   **Switching Logic**: Implemented in `LLMClient._switchboard`. If Prompt > 70% of TPM limit -> Switch to Scout.

### **B. Cost Control**
-   **Caching**: `openai/gpt-oss-20b` is used as the "Structure Model" to leverage **Prompt Caching** for massive savings on repetitive JSON schemas.
-   **Hard Limits**: `LLMClient` has built-in TPM tracking to prevent bill shock (even on Free Tier).

### **C. API Keys & Security**
-   **Required**: `GROQ_API_KEY` (Logic), `GUVI_API_KEY` (Auth).
-   **Missing Key Behavior**:
    -   If `GROQ` missing: System fails to start (Critical).
    -   If `GUVI` missing: Callbacks fail, Incoming API returns 403.
-   **Safety**: Keys are loaded via `app.config.settings` (.env).

### **D. Hackathon vs. Production**
-   **Hackathon Safe**: The `guvi_handler` includes a "Crash Guard" that returns a 200 OK even if the backend errors, ensuring stability points during judging.
-   **Production Ready**: The `orchestrator` loop and Database persistence are robust enough for real deployment, but the *Enforcement* layer needs real API integrations.