audit/06_Inter_Folder_Dependencies.md

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.