architecture-analysis

name	architecture-analysis
description	Analyzes codebase for SOLID principles violations, DDD patterns compliance, Clean Architecture layer dependencies, and common anti-patterns. Works with Python and TypeScript, with language-agnostic pattern detection.
allowed-tools	Read, Grep, Glob, Bash(wc:*), Bash(find:*), Bash(sort:*), Bash(head:*), Bash(tail:*), Bash(awk:*), Bash(grep:*), Bash(radon:*), Bash(vulture:*), Bash(command:*), Bash(jq:*), Bash(cat:*), Bash(uniq:*), Bash(cut:*), Bash(xargs:*)

Architecture Analysis - SOLID, DDD & Clean Architecture

Analyzes codebases for architectural violations, design pattern issues, and maintainability problems. Provides actionable recommendations with code examples.

---

Analysis Scope

Category	What We Check	Severity Range
SOLID Principles	SRP, OCP, LSP, ISP, DIP	CRITICAL - MEDIUM
DDD Patterns	Aggregates, Value Objects, Repositories	HIGH - LOW
Clean Architecture	Layer dependencies, boundary violations	CRITICAL - HIGH
Anti-Patterns	God Objects, Circular Dependencies	HIGH - MEDIUM
Code Metrics	Complexity, coupling, cohesion	HIGH - LOW

---

Step 1: Codebase Structure Analysis

Detect Project Layout

echo "=== Project Structure Analysis ==="

# Detect common architecture patterns
echo "--- Layer Detection ---"
for layer in domain application infrastructure presentation api services models controllers handlers; do
    [ -d "$layer" ] && echo "FOUND: $layer/"
    [ -d "src/$layer" ] && echo "FOUND: src/$layer/"
    [ -d "app/$layer" ] && echo "FOUND: app/$layer/"
done

File Distribution: Use the Glob tool to find all Python files (**/*.py) and TypeScript files (**/*.ts, **/*.tsx). Group results by top-level directory to understand file distribution across layers.

Identify Architecture Pattern

Pattern	Indicators
Clean Architecture	domain/, application/, infrastructure/, presentation/
Hexagonal	ports/, adapters/, core/
DDD	aggregates/, entities/, value_objects/, repositories/
MVC	models/, views/, controllers/
Layered	services/, repositories/, controllers/

---

Step 2: SOLID Principles Analysis

SRP - Single Responsibility Principle

Detection: Classes/files doing too many things.

Metrics:

• Lines of code per file: >500 = HIGH violation
• Methods per class: >15 = HIGH violation
• Different responsibilities in one class

Large files detection: Use the Glob tool to find all **/*.py and **/*.ts/**/*.tsx files. Then Read each file to check its line count. Flag files with >500 lines as HIGH severity SRP violations.

Classes with many methods: Use the Grep tool to search for class in Python files, then Read each matching file and count def occurrences. Flag files with >15 methods as HIGH severity.

Report Format:

{
  "principle": "SRP",
  "severity": "HIGH",
  "file": "src/services/user_service.py",
  "metrics": {
    "lines_of_code": 650,
    "method_count": 25
  },
  "description": "UserService handles authentication, profile management, notifications, and billing - 4 distinct responsibilities",
  "remediation": "Split into UserAuthService, UserProfileService, NotificationService, BillingService",
  "code_example": {
    "before": "class UserService:\n    def login()\n    def update_profile()\n    def send_notification()\n    def process_payment()",
    "after": "class UserAuthService:\n    def login()\n\nclass UserProfileService:\n    def update_profile()"
  }
}

---

OCP - Open/Closed Principle

Detection: Long switch/if-elif chains that need modification for new types.

Long if-elif chains: Use the Grep tool to search for elif in Python files. Read files with many matches (>5 elif per file) and flag as MEDIUM OCP violations.

Large switch statements: Use the Grep tool to search for switch and case in TypeScript files. Files with >5 case statements may indicate OCP violations.

Type checking patterns: Use the Grep tool to search for isinstance in Python files and typeof.*=== or instanceof in TypeScript files. These patterns often indicate OCP violations.

Pattern to Flag:

# BAD: Violates OCP - must modify for new types
def calculate_area(shape):
    if isinstance(shape, Circle):
        return 3.14 * shape.radius ** 2
    elif isinstance(shape, Rectangle):
        return shape.width * shape.height
    elif isinstance(shape, Triangle):  # New type = modification
        return 0.5 * shape.base * shape.height

# GOOD: Open for extension, closed for modification
class Shape(ABC):
    @abstractmethod
    def area(self) -> float: ...

class Circle(Shape):
    def area(self) -> float:
        return 3.14 * self.radius ** 2

---

LSP - Liskov Substitution Principle

Detection: Subclasses that change parent behavior unexpectedly.

Potential LSP violations: Use the Grep tool to search for raise NotImplementedError and throw new Error.*not implemented and pass # type: ignore across Python and TypeScript files.

Override analysis: Use the Grep tool to search for super() in Python files to find override locations. Read those files to verify subclasses honor parent contracts.

Manual AI Review Required:

• Check if subclasses honor parent contracts
• Look for methods that throw exceptions parent doesn't define
• Verify return types are covariant

---

ISP - Interface Segregation Principle

Detection: Large interfaces/protocols with many methods.

Large interfaces (Python): Use the Grep tool to search for class.*Protocol and class.*ABC in Python files. Read each matching file and count methods in the interface. Flag interfaces with >7 methods as MEDIUM ISP violations.

Large interfaces (TypeScript): Use the Grep tool to search for ^interface and ^export interface in TypeScript files. Read each matching file and count method signatures. Flag interfaces with >7 methods as MEDIUM ISP violations.

Pattern to Flag:

// BAD: Fat interface - forces clients to implement unused methods
interface UserRepository {
  findById(id: string): User;
  findAll(): User[];
  save(user: User): void;
  delete(id: string): void;
  findByEmail(email: string): User;
  findByRole(role: string): User[];
  countByStatus(status: string): number;
  exportToCsv(): string;  // Why is this here?
}

// GOOD: Segregated interfaces
interface UserReader {
  findById(id: string): User;
  findByEmail(email: string): User;
}

interface UserWriter {
  save(user: User): void;
  delete(id: string): void;
}

---

DIP - Dependency Inversion Principle

Detection: High-level modules importing low-level details.

Domain -> Infrastructure violations (Python): Use the Grep tool to search for from.*infrastructure and import.*infrastructure in Python files within domain/ or src/domain/ directories. Also search for from.*database, import.*database in domain directories.

Direct DB access in domain: Use the Grep tool to search for session\., cursor\., execute(, query( in Python files within domain directories.

Core -> Adapter violations (TypeScript): Use the Grep tool to search for from.*adapters, from.*infrastructure, from.*database in TypeScript files within src/core/ or src/domain/ directories.

Direct HTTP/DB in domain: Use the Grep tool to search for fetch(, axios\., prisma\., mongoose\. in TypeScript files within domain directories.

Correct Dependency Direction:

[Presentation/API] ──depends on──> [Application/Use Cases]
                                          │
                                   depends on
                                          ▼
[Infrastructure] ──implements──> [Domain (Interfaces)]

---

Step 3: Clean Architecture Analysis

Layer Boundary Violations

Layer detection: Use the Glob tool to find directories named domain, application, infrastructure, presentation, api (e.g., **/domain/, **/application/).

Forbidden import patterns:

• Domain layer: Use the Grep tool to search for from.*infrastructure, from.*presentation, from.*api, import.*infrastructure in all Python and TypeScript files within any domain/ directory found above. These are CRITICAL violations.
• Application layer: Use the Grep tool to search for from.*presentation, from.*api, from.*controllers in all Python and TypeScript files within any application/ directory found above. These are HIGH violations.

Layer Dependency Matrix

From \ To	Domain	Application	Infrastructure	Presentation
Domain	OK	NO	NO	NO
Application	OK	OK	NO	NO
Infrastructure	OK	OK	OK	NO
Presentation	OK	OK	OK	OK

---

Step 4: DDD Pattern Analysis

Aggregate Detection

Aggregate candidates: Use the Grep tool to search for Repository, AggregateRoot, @aggregate across Python and TypeScript files.

Aggregate boundary violations: Use the Grep tool to search for .entities., .children., get_child, find_child — accessing child entities directly may violate aggregate boundaries.

Value Object Detection

Potential value objects (Python): Use the Grep tool to search for @dataclass and @frozen in Python files. Read matching files to check for identity fields (id:, _id:) — their absence suggests value objects.

Mutable value objects (violation): Use the Grep tool to search for @dataclass in Python files. Read matching files to verify frozen=True is set. Mutable dataclasses used as value objects are violations.

Potential value objects (TypeScript): Use the Grep tool to search for readonly and Readonly< in TypeScript files.

Anemic Domain Model Detection

Anemic entities: Use the Grep tool to search for @dataclass and class.*Entity in Python files. Read each matching file and count def occurrences. Files with <3 methods may be anemic domain models (LOW severity).

Business logic location: Use the Grep tool to search for def.*validate, def.*calculate, def.*process in Python files within service directories. Business logic in services rather than entities indicates anemic domain model.

---

Step 5: Anti-Pattern Detection

God Object

God Object detection: Use the Glob tool to find all **/*.py and **/*.ts/**/*.tsx files. Read each file and check:

• Files with >500 lines AND >20 methods = CRITICAL (God Object)
• Files with >500 lines OR >20 methods = HIGH
• Focus on files in services/, handlers/, controllers/ directories first

Circular Dependencies

Import error indicators: Use the Grep tool to search for ImportError, circular import, cannot import name in Python files.

Mutual import analysis: Use the Grep tool to search for ^from \. and ^import \. in Python files to find relative imports. Read files with relative imports and trace import chains to detect circular dependencies.

Deep Inheritance

Inheritance analysis: Use the Grep tool to search for class.*\( in Python files (excluding ABC, Protocol, Exception, Enum). Read matching files to trace inheritance chains. Flag chains >3 levels deep as MEDIUM severity.

Inheritance depth: Use the Grep tool to search for super().__init__ and super(). in Python files to identify classes using super calls. Multiple super calls in a chain indicate deep inheritance.

Tight Coupling

Direct instantiation in Python constructors: Use the Grep tool to search for def __init__ in Python files. Read matching files and look for patterns like self.x = SomeClass() — direct instantiation instead of dependency injection.

Direct instantiation in TypeScript constructors: Use the Grep tool to search for constructor( in TypeScript files. Read matching files and look for new keyword inside constructors — indicates tight coupling instead of DI.

---

Step 6: Code Metrics (Python)

Cyclomatic Complexity (if radon available)

echo "=== Cyclomatic Complexity ==="

if command -v radon >/dev/null 2>&1; then
    echo "Running radon complexity analysis..."
    radon cc . -a -s --json -O /tmp/radon-results.json 2>/dev/null
    echo "Results saved to /tmp/radon-results.json"
else
    echo "radon not installed - using method length as proxy"
fi

After radon scan: Read /tmp/radon-results.json with the Read tool. Look for functions/methods with complexity >10 (HIGH severity). Key fields per entry: .complexity, .lineno, .name.

If radon unavailable: Use the Grep tool to search for def and async def in Python files, then Read files to estimate function length as a complexity proxy.

Dead Code (if vulture available)

echo "=== Dead Code Detection ==="

if command -v vulture >/dev/null 2>&1; then
    echo "Running vulture dead code analysis..."
    vulture . --min-confidence 80 1>/tmp/vulture-results.txt 2>/dev/null
    echo "Results saved to /tmp/vulture-results.txt"
else
    echo "vulture not installed - skipping dead code detection"
fi

After vulture scan: Read /tmp/vulture-results.txt with the Read tool and analyze dead code findings.

---

Report Format

For each issue found, report in this structure:

{
  "severity": "CRITICAL|HIGH|MEDIUM|LOW",
  "category": "Architecture|Design|Maintainability",
  "principle": "SRP|OCP|LSP|ISP|DIP|DDD|CleanArch|AntiPattern",
  "title": "Descriptive title",
  "file": "path/to/file.py",
  "line": 1,
  "end_line": 500,
  "metrics": {
    "lines_of_code": 500,
    "method_count": 25,
    "cyclomatic_complexity": 45
  },
  "description": "Clear explanation of the violation",
  "impact": "Why this matters - testability, maintainability, etc.",
  "remediation": "How to fix it",
  "code_example": {
    "before": "// Problematic code",
    "after": "// Improved code"
  },
  "effort": "trivial|easy|medium|hard",
  "references": ["https://clean-code.com/srp"]
}

---

Severity Classification

Severity	Criteria	Action
CRITICAL	Architecture boundary violation, God Object in core domain	Block merge
HIGH	SOLID violation affecting testability, DIP violation	Fix before release
MEDIUM	Design smell, complexity issue	Plan fix
LOW	Minor pattern deviation, style preference	Track

---

Final Summary Format

{
  "analysis_summary": {
    "files_analyzed": 150,
    "architecture_pattern": "Clean Architecture",
    "layers_detected": ["domain", "application", "infrastructure", "api"]
  },
  "solid_analysis": {
    "srp_violations": 3,
    "ocp_violations": 1,
    "lsp_violations": 0,
    "isp_violations": 2,
    "dip_violations": 4
  },
  "clean_arch_analysis": {
    "layer_violations": 2,
    "dependency_direction_issues": 3
  },
  "anti_patterns": {
    "god_objects": 1,
    "circular_dependencies": 0,
    "deep_inheritance": 2,
    "tight_coupling": 5
  },
  "metrics": {
    "avg_file_size": 120,
    "max_file_size": 650,
    "avg_complexity": 5,
    "max_complexity": 25
  },
  "top_issues": [
    {
      "severity": "CRITICAL",
      "title": "God Object: UserService",
      "file": "src/services/user_service.py"
    }
  ],
  "recommendations": [
    "Split UserService into smaller services",
    "Fix 4 DIP violations in domain layer",
    "Add interfaces for tight coupling in handlers"
  ]
}

---

Red Flags - STOP if you

• Skip any SOLID principle check
• Report violations without file paths and line numbers
• Miss layer boundary violations in Clean Architecture projects
• Provide remediation without code examples for HIGH+ issues

When these occur: Go back and complete the missed analysis.

---

Final Checklist

Before completing architecture analysis, verify:

• Detected project architecture pattern
• Analyzed all SOLID principles (SRP, OCP, LSP, ISP, DIP)
• Checked Clean Architecture layer boundaries (if applicable)
• Checked DDD patterns (if applicable)
• Detected anti-patterns (God Objects, circular deps, etc.)
• Collected code metrics
• Each finding has: severity, principle, file, line, remediation
• Code examples provided for HIGH+ issues
• Generated summary with top issues
• Provided actionable recommendations