# Topic 6: Inter-Folder Dependencies

**Audit Date**: 2026-02-01
**Auditor**: Agent Antigravity
**Scope**: Architectural Layer Analysis

---

## 1. Layer Dependency Rules
The system enforces a **Strict Unidirectional Flow**:
`Ingress (API)` -> `Logic (Agents)` -> `Intelligence` & `Persistence`.

### A. Allowed Imports
| From Folder | Can Import From | Violations Found? |
| :--- | :--- | :--- |
| **`app/api`** | `app/utils`, `app/agents`, `app/middleware` | **NONE** |
| **`app/agents`** | `app/core`, `app/intelligence`, `app/decoys`, `app/database` | **NONE** |
| **`app/intelligence`** | `app/core` (LLM), `app/utils` (Logger) | **NONE** |
| **`app/core`** | `app/config` | **NONE** |
| **`app/database`** | `app/config` | **NONE** |

### B. Forbidden Cycles (Verified)
*   **`app/core`** NEVER calls **`app/agents`**. (Infrastructure cannot depend on Logic).
*   **`app/database`** NEVER calls **`app/api`**. (Persistence cannot depend on Ingress).
*   **`app/utils`** is a leaf node (mostly), though `guvi_handler` acts as a specialized bridge.

---

## 2. Cross-Cutting Concerns (Shared Folders)

### **`app/config`**
*   **Status**: Imported by ALL.
*   **Role**: Source of Truth for Environment Variables, API Keys (`settings`).
*   **Safety**: Does not import ANY other app module to prevent circular dependency.

### **`app/utils/logger`**
*   **Status**: Imported by ALL.
*   **Role**: Standardized structured logging (`AgentLogger`).

---

## 3. Critical Bridges

### **The Handler Bridge (`app/utils/guvi_handler.py`)**
This module is the **only** exception that sits between `API` and `Agents`.
*   **Why?** To translate the unique "GUVI Hackathon JSON" into the system's internal "Standard Message Format".
*   **Dependency**: Imports `orchestrator`, but `orchestrator` does NOT import `guvi_handler`. (Safe).

### **The LLM Bridge (`app/core/llm_client.py`)**
This is the gateway to the outside world (Groq/OpenAI).
*   **Usage**: Used by `agents`, `intelligence`, and `enforcement`.
*   **Isolation**: It knows nothing about "Scams" or "Personas". It only knows "Prompts" and "Models".

---

## 4. Architectural Score
**modularity_score**: **10/10**
The folder structure perfectly mirrors a "Clean Architecture" approach. Replacing the API (FactAPI) with a Telegram Bot interface would require changes ONLY in `app/api`, without touching `app/agents`.