Architecture Analysis

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

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

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

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

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

Source: AppVerk/av-marketplace — distributed by TomeVault.