# Topic 3: File-by-File Responsibilities

**Audit Date**: 2026-02-01
**Auditor**: Agent Antigravity (Senior Architect)
**Scope**: Granular File Analysis

---

## 1. `app/agents/` (The autonomous Core)
| File | Status | Responsibility | Key Class/Func |
| :--- | :--- | :--- | :--- |
| **`orchestrator.py`** | **REAL** | Central OODA Loop controller. Coordinates all other agents and manages lifecycle. | `HoneypotOrchestrator` |
| **`scam_detector.py`** | **REAL** | Hybrid classification engine using Regex heuristics + LLM verification. | `ScamDetector.detect()` |
| **`persona_engine.py`** | **REAL** | Manages personality state, selects personas, and generates style-matched responses. | `PersonaEngine.generate_response()` |
| **`intelligence_extractor.py`** | **REAL** | Parses incoming text to extract PII (UPI, Phone, Bank) using Regex/Models. | `IntelligenceExtractor.extract()` |
| **`conversation_manager.py`** | **REAL** | Manages session state, phase tracking (Hook/Engage), and history persistence. | `ConversationManager` |
| **`adaptive_strategy.py`** | **REAL** | Decides the next strategic move (Stall, Escalate, Bait) based on risk scores. | `AdaptiveStrategyAgent` |

---

## 2. `app/intelligence/` (Analysis & Enrichment)
| File | Status | Responsibility | Key Class/Func |
| :--- | :--- | :--- | :--- |
| **`threat_engine.py`** | **REAL** | Aggregates session data to identify Campaign clusters (MITRE mapping). | `ThreatIntelligenceEngine` |
| **`risk_scorer.py`** | **REAL** | Calculates 0.0-1.0 Risk Score based on keyword density and LLM verdict. | `RiskScoringEngine` |
| **`telemetry.py`** | **REAL** | Extracts technical signals (IP, User-Agent, Devices) for fingerprints. | `TelemetryCollector` |
| **`scammer_profiler.py`** | **REAL** | Builds longitudinal profiles of attackers (Psych/Tech capabilities). | `ScammerProfiler` |
| **`mitre_mapper.py`** | **REAL** | Maps observed request patterns to specific MITRE ATT&CK TTP IDs. | `MitreMapper` |
| **`honeytokens.py`** | **REAL** | Generators for Fake Creds (Bank Login, UPI) to give to scammers. | `HoneyTokenManager` |
| **`graph_threat_intel.py`** | **HYBRID** | Simulates a GraphDB link analysis (Node connections). | `GraphThreatIntel` |
| **`enrichment_service.py`** | **SIMULATED** | Mocks external lookups (TrueCaller/Bank Verification) for demo purposes. | `EnrichmentService` |
| **`threat_feeds.py`** | **SIMULATED** | Generates realistic "Live Feed" triggers for the dashboard UI. | `ThreatFeedService` |

---

## 3. `app/core/` (Infrastructure)
| File | Status | Responsibility | Key Class/Func |
| :--- | :--- | :--- | :--- |
| **`llm_client.py`** | **REAL** | The "Switchboard". Handles API calls, Retries, Model Routing, and Safety Checks. | `LLMClient` |
| **`model_registry.py`** | **REAL** | Configuration file defining Model TPM limits, Context Windows, and Capabilities. | `MODELS` dict |
| **`prompts.py`** | **REAL** | Jinja2 templates for System Prompts (Detector, Persona, Reasoner). | `PromptManager` |
| **`memory.py`** | **REAL** | Abstracted memory interface (currently wraps DB access). | `MemoryManager` |
| **`static_prompts.py`** | **REAL** | Fallback prompts hardcoded for resilience if template loading fails. | `STATIC_PROMPTS` |

---

## 4. `app/api/` (Ingress)
| File | Status | Responsibility | Keys |
| :--- | :--- | :--- | :--- |
| **`routes.py`** | **REAL** | Defines all FastAPI endpoints. Handles Request/Response lifecycle. | `/analyze`, `/guvi` |
| **`schemas.py`** | **REAL** | Strict Pydantic models for Input/Output validation. | `GUVIInputRequest`, `AnalyzeResponse` |

---

## 5. `app/utils/` (Shared Tools)
| File | Status | Responsibility | Note |
| :--- | :--- | :--- | :--- |
| **`guvi_handler.py`** | **REAL** | **CRITICAL**. Translates external Hackathon JSON to Internal format. | Crash-safe wrapper. |
| **`callback_client.py`** | **REAL** | **CRITICAL**. Sends the mandatory `updateHoneyPotFinalResult` POST. | Uses `tenacity` for retries. |
| **`dossier_generator.py`** | **REAL** | Generates Markdown reports for Law Enforcement. | |

---

## Critical Observation on "Realness"
*   **Core Logic**: 100% Real. All decision making (`agents`), extraction (`intelligence`), and communication (`core` & `api`) runs actual code.
*   **External World**: Components that require unavailable 3rd party access (Police DB, Bank Freeze API, TrueCaller) are **Simulated** (`enforcement/`, `enrichment_service.py`) to provide a complete "feel" without blocking execution.

**Proceed to the next topic? If yes, provide topic number.**