# Topic 4: Execution Flow (Request → Response → Callback)

**Audit Date**: 2026-02-01
**Auditor**: Agent Antigravity (Senior Architect)
**Scope**: End-to-End Lifecycle Analysis

---

## 1. High-Level Lifecycle
The system processes requests in a **Synchronous Analysis / Asynchronous Reporting** pattern.
1.  **Ingress**: Standard REST receive.
2.  **Logic**: Real-time "OODA Loop" processing (Observe-Orient-Decide-Act).
3.  **Response**: Immediate JSON return to platform.
4.  **Callback**: Background task for mandatory reporting.

---

## 2. Step-by-Step Flow

### **Phase A: Ingress (The Request)**
1.  **Endpoint**: `POST /api/guvi/analyze` (`app/api/routes.py`) receives the payload.
2.  **Validation**: `app/api/schemas.py` validates `sessionId`, `message`, and `x-api-key`.
3.  **Handover**: Request is passed to `guvi_handler.process_guvi_message()`.

### **Phase B: The OODA Loop (The Brain)**
*Managed by `app/agents/orchestrator.py`*

#### 1. Observe (Detection)
*   **Action**: `ScamDetector.detect(message)`
*   **Logic**:
    *   **Heuristic Check**: Regex searches for known scam patterns (UPI handles, "Verify Now", "Block").
    *   **LLM Verification**: If regex is ambiguous, `Llama-3.3` analyzes intent.
*   **Output**: `scam_type` (e.g., "bank_fraud"), `confidence` (0.0-1.0).

#### 2. Orient (Intelligence)
*   **Action**: `IntelligenceExtractor.extract(message)` & `ThreatEngine.analyze()`
*   **Logic**:
    *   Extracts PII (UPI, Phone, URL) using strict regex.
    *   Enriches data via `EnrichmentService` (Simulated lookups).
    *   Maps behavior to MITRE ATT&CK TTPs.
*   **Output**: `aggregated_intelligence` dict.

#### 3. Decide (Strategy)
*   **Action**: `ConversationManager.determine_phase()`
*   **Logic**:
    *   **Hook**: If msg_count < 2.
    *   **Engage**: If trust needs building.
    *   **Extract**: If PII is missing.
    *   **Stall**: If intelligence is complete.
*   **Output**: `current_phase`, `should_finalize` boolean.

#### 4. Act (Response)
*   **Action**: `PersonaEngine.generate_response()`
*   **Logic**:
    *   Selects Persona (e.g., "Elderly Victim", "Naive Student").
    *   Injects `context` (Phase, Scam Type, History).
    *   **LLM Generation**: Generates raw text response.
    *   **Honeytokens**: Injects Fake Bank Credentials if prompted.
*   **Output**: Human-like text reply.

### **Phase C: Egress (The Response)**
1.  **Formatting**: `guvi_handler` maps the internal result to the strict `GUVIOutputResponse` schema (`status`, `reply`).
2.  **Return**: HTTP 200 JSON sent back to the caller immediately.

### **Phase D: The Callback (Mandatory Reporting)**
*Triggered inside `guvi_handler.process_guvi_message`*
1.  **Check**: If `scamDetected=True` AND `should_finalize=True`.
2.  **Async Task**: `guvi_callback.send_final_result()` is scheduled via `asyncio.create_task`.
3.  **Optimization**:
    *   **Retries**: Uses `tenacity` library to retry 5 times if GUVI server is down.
    *   **Payload**: Sends strict 5-key intelligence format.
    *   **Headers**: Includes `x-api-key` for identification.

---

## 3. Dependency Graph (Who Calls Whom)

```mermaid
graph TD
    User[GUVI Platform] -->|POST /analyze| Ingress[api/routes.py]
    Ingress --> Handler[utils/guvi_handler.py]
    Handler --> Orchestrator[agents/orchestrator.py]
    
    subgraph "The Brain (Orchestrator)"
        Orchestrator --> Detector[scam_detector.py]
        Orchestrator --> Extractor[intel_extractor.py]
        Orchestrator --> Manager[conversation_manager.py]
        Orchestrator --> Persona[persona_engine.py]
    end
    
    subgraph "Infrastructure"
        Detector --> LLM[core/llm_client.py]
        Persona --> LLM
        LLM --> GroqAPI[Groq / OpenAI]
    end
    
    Orchestrator -->|Result| Handler
    Handler -->|Json| User
    
    Handler -.->|Async Trigger| Callback[utils/callback_client.py]
    Callback -->|POST Result| User
```

---

## 4. Critical Design Choice: Async Callback
**Why?** The User (Judge) expects a fast response (latency < 1-2s).
If we waited for the *Final Result* HTTP call to finish before replying to the chat, it would add 500ms+ latency.
**Solution**: The chat reply is sent **Synchronously** (Fast), while the Final Report is sent **Asynchronously** (Reliable).

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