# Topic 2: Folder-by-Folder Responsibilities

**Audit Date**: 2026-02-01
**Auditor**: Agent Antigravity (Senior Architect)
**Status**: Verified via `list_dir`

---

## 1. Root Structure
| Folder | Status | Responsibility | Key Files |
| :--- | :--- | :--- | :--- |
| **`app/`** | **REAL** | Core application source code. | `main.py`, `config.py` |
| **`web/`** | **REAL** | Frontend static assets (HTML/CSS/JS) for the Admin Dashboard. | `index.html`, `dashboard.js` |
| **`docs/`** | **REAL** | Documentation and markdown artifacts. | `COST_OPTIMIZATION.md` |
| **`data/`** | **REAL** | Local persistence storage (SQLite). | `honeypot.db` |
| **`audit/`** | **REAL** | Technical Audit reports (This folder). | `01_System_Architecture.md` |

---

## 2. Application Core (`app/`)
This layer handles the lifecycle, configuration, and entry points.

### **`app/api/` (Ingress)**
**Status**: **REAL**
**Responsibility**: Defines the REST Interface and Data Contracts.
*   **`routes.py`**: Contains all FastAPI endpoints (`/analyze`, `/guvi`, `/metrics`).
*   **`schemas.py`**: Pydantic models enforcing strict input/output validation.

### **`app/core/` (Infrastructure)**
**Status**: **REAL**
**Responsibility**: Low-level clients and system configuration.
*   **`llm_client.py`**: The "Router" for all LLM calls (Groq/OpenAI switchboard).
*   **`model_registry.py`**: Defines token limits and model capabilities.
*   **`prompts.py`**: Jinja2 templates for system prompts.
*   **`memory.py`**: Redis/In-Memory conversation state management.

### **`app/agents/` (The Brain)**
**Status**: **REAL**
**Responsibility**: Autonomous decision-making logic.
*   **`orchestrator.py`**: The central controller of the OODA loop.
*   **`scam_detector.py`**: Hybrid classification (Regex + LLM).
*   **`persona_engine.py`**: Manages personality state and response generation.
*   **`adaptive_strategy.py`**: Decides when to hook, engage, or stall.

---

## 3. Intelligence & Simulation (`app/intelligence/`)
**Status**: **HYBRID**
**Responsibility**: Advanced analysis, accumulation, and external data mapping.

| File | Status | Responsibility |
| :--- | :--- | :--- |
| **`threat_engine.py`** | **REAL** | Clusters sessions into "Campaigns". |
| **`telemetry.py`** | **REAL** | Extract IP, Geo, and User-Agent data. |
| **`mitre_mapper.py`** | **REAL** | Maps behaviors to MITRE ATT&CK TTPs. |
| **`enrichment_service.py`** | **MOCKED** | Simulates phone/UPI lookups (returns validity boolean). |
| **`threat_feeds.py`** | **MOCKED** | Generates realistic dummy feeds for dashboard viz. |
| **`scammer_profiler.py`** | **REAL** | Builds longitudinal profiles of attackers. |

---

## 4. Enforcement & Compliance (`app/enforcement/`)
**Status**: **SIMULATED**
**Responsibility**: Interfacing with Law Enforcement (NCRP) and Banks (NPCI).

| File | Status | Responsibility |
| :--- | :--- | :--- |
| **`police_api.py`** | **SIMULATED** | Mocks the API calls to file police reports. Returns valid-looking Fake Report IDs. |
| **`stakeholder_exports.py`** | **REAL** | Generates actual JSON export bundles for regulators. |
| **`awareness.py`** | **REAL** | Generates victim protection advice strings. |

---

## 5. Tools & Utilities (`app/utils/` & `app/decoys/`)
**Status**: **REAL**
**Responsibility**: Shared logic and Trap generation.

*   **`guvi_handler.py`**: **CRITICAL**. Translates external Hackathon payload format to internal logic.
*   **`callback_client.py`**: **CRITICAL**. Sends the mandatory final report to GUVI.
*   **`fake_endpoints.py`** (`decoys`): Generates "Honeytoken" pages (Fake Bank Login) to bait scammers.

---

## 6. Middleware (`app/middleware/`)
**Status**: **REAL**
**Responsibility**: Traffic control and security.
*   **`rate_limiter.py`**: Enforces RPM limits to protect the LLM budget.

---

## 7. Key Findings
1.  **Strict Separation**: The "Brain" (`agents`) is completely decoupled from the "Body" (`api`), satisfying the Modular Monolith pattern.
2.  **Simulation Boundary**: The boundary between **Real** (Logic/Data) and **Simulated** (Enforcement/Feeds) is clean. No core logic depends on a simulated output.
3.  **Hackathon Ops**: The `guvi_handler` and `callback_client` are isolated in `utils`, ensuring the core system remains generic while satisfying specific hackathon constraints.

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