Architecture Review Quick Reference

This skill provides a condensed checklist for identifying architecture violations during code review or development.

When to Activate

• •Reviewing code that changes project structure or adds new modules
• •Working with dependency injection, layer boundaries, or module dependencies
• •Creating new packages, directories, or modules
• •Refactoring architecture (extracting services, separating layers)
• •Reviewing import statements for dependency direction compliance
• •Evaluating DTO/Entity separation or data flow patterns
• •Assessing microservice communication patterns

Core Principles

1. Dependencies Flow Inward

Outer layers depend on inner layers, never the reverse. Domain/core has zero outward dependencies.

[Controller/API] --> [Service/UseCase] --> [Domain/Entity] --> [nothing]
     ^                     ^                    ^
     |                     |                    |
[Infrastructure]    [Infrastructure]      [NEVER depends on outer]

2. Detect, Don't Prescribe

Report the detected architecture style. Don't force hexagonal on a simple CRUD app. Match analysis to project maturity.

3. Context Matters

Read surrounding code before flagging. A pattern that looks bad in isolation may be an intentional trade-off.

6-Step Analysis Workflow

Quick Reference by Violation Type

Critical Violations

High Violations

Medium Violations

Low Violations

Top 5 Most Common Architecture Violations

1. Domain Depends on Infrastructure (V-C1)

// BAD: domain/model/Order.kt
import javax.persistence.Entity  // Infrastructure leak!

// GOOD: Pure domain model + infrastructure/persistence/OrderEntity.kt
data class Order(val id: OrderId, val customerId: CustomerId, val totalAmount: Money)

2. Controller Skipping Service Layer (V-H1)

// BAD
@RestController
class OrderController(private val orderRepository: OrderRepository) { ... }

// GOOD
@RestController
class OrderController(private val orderService: OrderService) { ... }

3. Entity Exposed to API (V-H2)

# BAD
@router.get("/users/{id}")
async def get_user(id: int, db: Session = Depends(get_db)):
    return db.query(UserModel).get(id)  # Leaks all fields

# GOOD
@router.get("/users/{id}", response_model=UserResponse)
async def get_user(id: int, service: UserService = Depends()):
    return service.find_by_id(id)

4. Hard-coded Dependencies (V-H4)

// BAD
export class OrderService {
    private repo = new PostgresOrderRepo() // Tight coupling!
}

// GOOD
@Injectable()
export class OrderService {
    constructor(private readonly repo: OrderRepository) {}
}

5. Business Logic in Controller (V-H3)

// BAD: Controller calculates, validates, notifies
@PostMapping("/orders")
fun createOrder(@RequestBody req: CreateOrderRequest): ResponseEntity<OrderDto> {
    val total = req.items.sumOf { it.price * it.quantity }
    if (total > 10000) notificationService.notifyAdmin("Large order")
    // ...
}

// GOOD: Delegate to service
@PostMapping("/orders")
fun createOrder(@RequestBody req: CreateOrderRequest): ResponseEntity<OrderDto> {
    return ResponseEntity.status(HttpStatus.CREATED).body(orderService.create(req))
}

Architecture Identification Matrix

DTO Separation Maturity

MSA Maturity Levels

Architecture Health Score

Base: 100 points

Deductions:
  Critical violation: -15 each
  High violation:     -8 each
  Medium violation:   -3 each
  Low violation:      -1 each

Bonuses:
  Architecture tests (ArchUnit):  +5
  API documentation:              +3
  Global exception handler:       +2
  Consistent naming:              +3
  DTO separation Level 2+:        +2

Rating:
  90-100: Excellent | 75-89: Good | 60-74: Fair | 40-59: Poor | 0-39: Critical

Severity Guide

Detailed Guide

For detailed analysis methodology, Bad/Good code examples per violation, and detection patterns, refer to the guide below:

• •Architecture Review Guide - Full methodology including 6-step analysis workflow, Violation Checklist (V-C1~V-L3), and Health Score calculation

This skill (SKILL.md) serves as a quick reference. For in-depth analysis, use the guide's detection patterns and code examples.

Integration with Other Tools

• •Use /arch-review [target] command for structured analysis with full report
• •Use /analyze --focus architecture for broader multi-domain assessment
• •The arch-reviewer agent contains the complete methodology with all code examples
• •Use /perf-review for complementary performance-focused analysis
• •This skill provides quick reference during regular development

Remember: Architecture matters most at scale. For small CRUD apps, pragmatism beats purity. Always consider project maturity and team size when evaluating violations. Detect the intended architecture, validate conformance, and provide actionable feedback.