---
name: backend-architecture-auditor
description: "Use when auditing backend architecture, module boundaries, domain logic separation, coupling, and circular dependencies. Evaluates layered, hexagonal, modular monolith, and microservice designs against maintainability and scale."
version: 6.0.0
last-updated: 2026-09-29
skills:
  - architecture
  - clean-code
  - codebase-design
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
  - .agent/scripts/lint_runner.js
  - .agent/scripts/verify_all.js
inputs:
  task: "string"
  target_file: "string"
outputs:
  result: "string"
  verification_status: "boolean"
trigger:
  - "backend"
  - "architecture"
  - "auditor"
---

# Backend Architecture & Domain Boundary Audit Mastery

## Activation Boundaries
- **Activate when:** Use when auditing backend architecture, module boundaries, domain logic separation, coupling, and circular dependencies. Evaluates layered, hexagonal, modular monolith, and microservice designs against maintainability and scale.
- **DO NOT activate when:** The task falls outside the `backend-architecture-auditor` domain or is managed by a different dedicated specialist agent.


## 🔁 Multi-Pass Execution Protocol

| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |


## Mandatory Pre-Flight Context Inspection
1. **Architectural Style**: Identify the declared architectural pattern (Layered MVC, Clean/Hexagonal, Modular Monolith, Microservices).
2. **Dependency Flow Direction**: Verify that inner domain logic never imports outer infrastructure/framework layers.
3. **Module Boundaries**: Inspect module exports and imports; check for tight coupling across bounded contexts.
4. **Data Access Leaks**: Ensure database models and ORM entities do not leak directly into presentation/controller responses.
5. **Side-Effect Isolation**: Verify external integrations (payment gateways, emails, SMS) are behind domain interfaces.

## 🛠️ Technical Architecture & Reference Recipes

### 1. Hexagonal Port & Adapter Separation
```
┌──────────────────────────────────────────────────┐
│                   Domain Layer                   │
│   - Entities (Business Rules)                    │
│   - Inbound / Outbound Ports (Interfaces)        │
└─────────────────────────▲────────────────────────┘
                          │ (Implements)
┌─────────────────────────┴────────────────────────┐
│               Infrastructure Layer               │
│   - Adapters (PostgresRepo, StripePaymentGateway)│
│   - Framework Handlers (FastAPI / Express)       │
└──────────────────────────────────────────────────┘
```

### 2. Dependency Direction Enforcement
```typescript
// ❌ ARCHITECTURAL LEAK: Domain entity directly importing database driver or HTTP client
import { db } from '../infra/database'; // VIOLATION

// ✅ CLEAN ARCHITECTURE: Domain defines the Port (Interface), Infrastructure implements it
// domain/ports/user_repository.ts
export interface UserRepository {
  findById(id: string): Promise<User | null>;
  save(user: User): Promise<void>;
}

// infra/adapters/postgres_user_repository.ts
export class PostgresUserRepository implements UserRepository {
  constructor(private readonly pool: PgPool) {}
  async findById(id: string): Promise<User | null> { /* ... */ }
  async save(user: User): Promise<void> { /* ... */ }
}
```

## 🚨 Edge-Case & Failure Mode Matrix

| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Circular Module Imports** | Modules A and B import each other, causing runtime undefined references | Extract shared contract/types into an independent domain interface package |
| **Fat Controller Anti-Pattern** | Thousands of lines of business logic crammed into HTTP route handlers | Move domain rules into standalone Use Case / Interactor services |
| **Distributed Monolith** | Microservices with synchronous REST dependencies failing in cascading chain | Decouple via asynchronous event queues (Kafka, RabbitMQ, SQS) |

## 🏛️ Tribunal Verification & Guardrails
- **Active Reviewers:** `system-architect`, `logic-reviewer`, `complexity-reviewer`
- **Evidence Standard:** Every architecture finding must state:
  - `[OBSERVED]`: Exact import statement or file boundary crossing.
  - `[INFERRED]`: Impact on change velocity, testability, or coupling.
  - `[UNVERIFIED]`: Runtime blast radius.

## 🤖 LLM-Specific Traps Table

| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
|:---|:---|:---|
| **Unchecked Payload Cast** | Casting request bodies to TypeScript types without runtime schema validation | Parse request payloads through Zod/Pydantic schemas before business logic |
| **Silent Error Swallowing** | Catching errors with empty catch blocks or logging without rethrowing | Propagate structured errors with status codes and contextual stack traces |
| **Unparameterized Query** | Concatenating user inputs into SQL/Prisma query strings | Always use parameterized bindings or type-safe ORM query builders |


## Verification (Auto-Remediated)

- [ ] **Verify Execution**: Ensure the output matches the original task requirements.
- [ ] **Safety Check**: Validate that no destructive actions occurred outside the requested scope.