/audit-clean-arch

name: rust:audit-clean-arch
description: Comprehensive audit of Rust codebase against Clean Architecture principles, identifying violations and improvement opportunities
allowed-tools: Read, Grep, Glob, Bash
author: Quintin Henry (https://github.com/qdhenry/)

Audit Clean Architecture Compliance

Perform a comprehensive audit of a Rust codebase against Clean Architecture principles, identifying violations, anti-patterns, and improvement opportunities.

Instructions

Audit the Rust codebase for clean architecture compliance: **$ARGUMENTS**

> **Note:** `$ARGUMENTS` can specify a path, specific concerns, or be empty for full audit. > Examples: > > - `/rust:audit-clean-arch` - Full audit of current directory > - `/rust:audit-clean-arch src/` - Audit specific path > - `/rust:audit-clean-arch --focus dependencies` - Focus on dependency violations

---

Clean Architecture Reference

┌─────────────────────────────────────────────────────────────┐
│                     Infrastructure                          │
│  (Setup, Config, DB Pools, Environment, Third-party Deps)  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    Adapters                           │  │
│  │  (HTTP Handlers, Persistence Impl, Crypto, Gateways)  │  │
│  │  ┌─────────────────────────────────────────────────┐  │  │
│  │  │               Application                        │  │  │
│  │  │  (Use Cases, Ports/Traits, App Errors)          │  │  │
│  │  │  ┌───────────────────────────────────────────┐  │  │  │
│  │  │  │              Domain                        │  │  │  │
│  │  │  │  (Entities, Domain Services, Value Objs)  │  │  │  │
│  │  │  └───────────────────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

THE DEPENDENCY RULE: Dependencies may only point INWARD
- Domain depends on NOTHING external
- Application depends only on Domain
- Adapters depend on Application (and implement its ports)
- Infrastructure depends on all inner layers (for wiring)

---

Phase 1: Structure Discovery

1.1 Identify Project Layout

First, map the codebase structure to identify layers:

# Find all Rust source files
find . -name "*.rs" -type f | head -50

# Look for common clean architecture patterns
ls -la src/

# Check for layer directories
for dir in domain application adapters infrastructure core lib api handlers services; do
  [ -d "src/$dir" ] && echo "Found: src/$dir"
done

1.2 Identify Layer Mapping

Map discovered directories to architectural layers:

| Layer | Common Directory Names | | ------------------ | --------------------------------------------------------------------------------------------------- | | **Domain** | `domain/`, `entities/`, `models/`, `core/domain/` | | **Application** | `application/`, `use_cases/`, `usecases/`, `services/` (business), `core/` | | **Adapters** | `adapters/`, `api/`, `handlers/`, `controllers/`, `repositories/`, `persistence/`, `http/`, `grpc/` | | **Infrastructure** | `infrastructure/`, `infra/`, `config/`, `db/`, `main.rs` setup code |

**Document the mapping:**

## Layer Mapping for This Codebase

- Domain: `src/???`
- Application: `src/???`
- Adapters: `src/???`
- Infrastructure: `src/???`
- Unclear/Mixed: `src/???`

---

Phase 2: Dependency Direction Audit

2.1 Analyze Module Dependencies

For each layer, check what it imports:

# Check domain layer imports (should be minimal)
grep -rn "^use " src/domain/ 2>/dev/null | grep -v "use crate::domain" | grep -v "use std::" | grep -v "use uuid::"

# Check application layer imports (should only use domain)
grep -rn "^use crate::" src/application/ 2>/dev/null

# Check adapters imports (should use application, not domain directly for business logic)
grep -rn "^use crate::" src/adapters/ 2>/dev/null

2.2 Dependency Violation Checklist

**CRITICAL VIOLATIONS (Red Flags):**

| Violation | Pattern to Find | Severity | | ---------------------------------- | -------------------------------------------------- | -------- | | Domain imports adapters | `use crate::adapters` in domain/ | CRITICAL | | Domain imports infrastructure | `use crate::infrastructure` in domain/ | CRITICAL | | Domain imports application | `use crate::application` in domain/ | CRITICAL | | Application imports adapters | `use crate::adapters` in application/ | HIGH | | Application imports infrastructure | `use crate::infrastructure` in application/ | HIGH | | Domain depends on web framework | `use axum`, `use actix`, `use rocket` in domain/ | CRITICAL | | Domain depends on DB | `use sqlx`, `use diesel`, `use sea_orm` in domain/ | CRITICAL |

2.3 Cargo.toml Analysis

Check if dependencies are properly scoped:

# Review Cargo.toml for dependency placement
cat Cargo.toml

# Check for feature flags that might isolate dependencies
grep -A5 "\[features\]" Cargo.toml

**Ideal Dependency Separation:**

• Domain crate: Only `uuid`, `chrono`, `thiserror` (minimal)
• Application crate: Domain + `async-trait`
• Adapters crate: Application + framework deps (`axum`, `sqlx`, `serde`)
• Infrastructure: All dependencies for wiring

---

Phase 3: Ports & Adapters Pattern Audit

3.1 Port Trait Detection

Look for traits that define boundaries (ports):

# Find async traits (common for repository ports)
grep -rn "async_trait" src/

# Find trait definitions in application layer
grep -rn "^pub tr