---
description: Evaluate system-level design, module responsibilities, and data ownership boundaries
alwaysApply: false
globs: ["bengal/**/*.py", "tests/**/*.py"]
---

# ARCH Audit (Architecture & Responsibility Audit)

Find structural design issues across modules, classes, and subsystems.

This audit operates **one level above flow and interaction audits**.
Instead of focusing on execution efficiency, it examines **system organization, ownership, and boundaries**.

Focus on identifying when:

- modules have unclear responsibilities
- logic is duplicated across components
- data ownership is ambiguous
- dependencies create tight coupling
- orchestration logic becomes centralized or tangled

**Goal:** Improve maintainability, clarity, and long-term scalability of the codebase.

**Shortcut:** `::arch` or `::arch-audit`

Works well alongside:
- `flow-audit`
- `ipa-audit`
- `sdc-audit`

**Works with:** `modules/architecture-patterns`, `modules/evidence-handling`

---

# Overview

Architectural issues rarely cause immediate failures but often lead to:

- increasing code duplication
- difficult refactoring
- performance inefficiencies
- fragile feature additions

This audit identifies **structural patterns that predict long-term complexity growth**.

Bengal-specific checks (model purity, orchestrator placement) remain in Steps 1–2.

---

# High Signal Indicators

Investigate immediately when you see:

- large modules doing many unrelated tasks
- duplicated logic across multiple files
- circular imports
- functions that move data across many modules
- "god classes" coordinating many subsystems
- data structures passed through many layers unchanged
- modules that mostly call other modules

---

# Architectural Symptoms

## 1. Unclear Data Ownership

### Symptom

Multiple modules modify or construct the same structure.

Example:

```
module_a.create_user()
module_b.update_user()
module_c.validate_user()
```

### Problem

No clear owner of the data model.

### Suggested Fix

Define a primary module responsible for creation, validation, and updates.

---

## 2. God Modules / Coordinator Classes

### Symptom

Large classes or modules coordinating many subsystems.

Example:

```
class SystemManager:
    load_config()
    validate_inputs()
    call_service()
    store_results()
```

### Problem

Centralized orchestration creates tight coupling.

### Suggested Fix

Split responsibilities into smaller components.

---

## 3. Logic Duplication

### Symptom

Similar logic appearing in multiple modules.

Example:

```
validation logic repeated in:
- loader.py
- resolver.py
- service.py
```

### Problem

Future changes require updating multiple places.

### Suggested Fix

Extract shared functionality into a single module.

---

## 4. Circular Dependencies

### Symptom

```
module_a → imports module_b
module_b → imports module_a
```

### Problem

Tight coupling between modules.

### Suggested Fix

Extract shared logic into a third module.

---

## 5. Data Passing Through Layers

### Symptom

Large structures passed through several functions without modification.

Example:

```
controller → service → helper → util
```

Each layer forwards the same data.

### Problem

Layers provide little value.

### Suggested Fix

Collapse unnecessary layers or move logic closer to data.

---

## 6. Boundary Violations

### Symptom

Modules accessing internal structures of other modules.

Example:

```
user_service._internal_cache
```

### Problem

Encapsulation broken.

### Suggested Fix

Expose a proper interface.

---

## 7. Feature Logic Scattered Across Files

### Symptom

Implementing a single feature requires modifying many modules.

Example:

```
parser.py
resolver.py
loader.py
validator.py
```

### Problem

Feature cohesion is weak.

### Suggested Fix

Group related logic into feature-focused modules.

---

# Bengal-Specific Checks

## Model Purity (`bengal/core/`)

Models **MUST NOT** contain logging, file I/O, or network calls:

```bash
grep -rn "logger\." bengal/core/
grep -rn "import logging" bengal/core/
grep -rn "\.write\(" bengal/core/
grep -rn "open(" bengal/core/
```

## Orchestrator Placement

All I/O in `bengal/orchestration/`, `bengal/cli/`, `bengal/server/`.
Models delegate to orchestrators.

## File Size Threshold

Files >400 lines → convert to package or split.

---

# Grep-Friendly Searches

```
rg "import .*" bengal/
rg "from .* import .*" bengal/
rg "class .*Manager" bengal/
rg "class .*Controller" bengal/
rg "pass" bengal/
```

Look for modules that primarily orchestrate or pass data.

---

# Procedure

### Step 1

Map major modules and their responsibilities.

### Step 2

Identify which modules create, own, and mutate core data structures.

### Step 3

Look for duplicated logic or scattered features.

### Step 4

Detect circular dependencies.

### Step 5

Evaluate whether responsibilities could be consolidated or better separated.

### Step 6 (Bengal)

Run model purity and orchestrator placement checks (see Bengal-Specific Checks).

---

# Co-located Scripts

```bash
# Run architecture audit script
python .cursor/rules/validation/architecture-audit/scripts/audit_arch.py bengal/

# Check specific subsystem
python .cursor/rules/validation/architecture-audit/scripts/audit_arch.py bengal/core/
```

---

# Output Format

```markdown
## ARCH Audit: [Subsystem]

### Findings

| File | Line | Architectural Issue | Suggested Fix |
|------|------|---------------------|----------------|
| system_manager.py | 22 | God class coordinating many subsystems | Split responsibilities |
| resolver.py | 87 | Validation logic duplicated | Extract shared validator |
| service.py | 144 | Circular dependency with loader | Introduce shared module |

### Summary

- **High**: ownership ambiguity or circular dependencies
- **Medium**: duplicated logic or scattered features
- **Low**: minor boundary violations
```

---

# Integration

Run when:

- performing major refactors
- adding new subsystems
- evaluating long-term maintainability
- conducting architecture reviews

Triggers:

- `::arch`
- `::arch-audit`
- "architecture audit"
- "module responsibility review"

---

# Related

- `flow-audit` — execution pipeline efficiency
- `ipa-audit` — interaction patterns between components
- `sdc-audit` — micro data structure optimizations
- `modules/architecture-patterns` — Bengal model/orchestrator patterns
