# Architecture Analysis > 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. - Skill: `tomevault-io/architecture-analysis` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/architecture-analysis` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/architecture-analysis/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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 | 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 ```bash 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:** ```json { "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:** ```python # 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:** ```typescript // 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) ```bash 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) ```bash 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: ```json { "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 ```json { "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](https://github.com/AppVerk/av-marketplace) — distributed by [TomeVault](https://tomevault.io).