architecture-analyzer

What this skill does

# Architecture Analyzer Skill

Analyzes and visualizes software architecture patterns and dependencies to support migration planning, module boundary identification, and architectural decision-making.

## Purpose

Enable comprehensive architecture analysis for:
- Component dependency mapping
- Layered architecture detection
- Coupling and cohesion metrics
- Architectural violation detection
- Module boundary identification
- Dependency graph generation

## Capabilities

### 1. Component Dependency Mapping
- Extract dependencies between modules/packages
- Map inter-service communications
- Identify external system integrations
- Track data flow between components
- Generate dependency matrices

### 2. Layered Architecture Detection
- Identify architectural layers (presentation, business, data)
- Detect layer violations
- Map cross-cutting concerns
- Analyze layer dependencies
- Validate architectural patterns

### 3. Coupling/Cohesion Metrics
- Calculate afferent coupling (Ca)
- Calculate efferent coupling (Ce)
- Compute instability index (I = Ce / (Ca + Ce))
- Measure module cohesion
- Identify highly coupled components

### 4. Architectural Violation Detection
- Detect circular dependencies between modules
- Identify layer bypassing
- Find direct database access from UI layers
- Check for proper abstraction usage
- Validate dependency rules

### 5. Module Boundary Identification
- Detect logical module groupings
- Identify bounded contexts
- Map shared kernel areas
- Analyze module interfaces
- Suggest decomposition boundaries

### 6. Dependency Graph Generation
- Generate DOT format graphs
- Create Mermaid diagrams
- Export to PlantUML
- Produce interactive visualizations
- Support multiple granularity levels

## Tool Integrations

This skill can leverage the following external tools when available:

| Tool | Purpose | Integration Method |
|------|---------|-------------------|
| Structure101 | Architecture visualization | Export analysis |
| Lattix | Dependency analysis | CLI / API |
| NDepend | .NET architecture analysis | CLI |
| JDepend | Java package dependencies | CLI |
| Madge | JavaScript/TypeScript | CLI |
| deptree | Python dependencies | CLI |
| go-arch-lint | Go architecture | CLI |
| ast-grep | Pattern matching | MCP Server |

## Usage

### Basic Analysis

```bash
# Invoke skill for architecture analysis
# The skill will analyze structure and dependencies

# Expected inputs:
# - targetPath: Path to codebase root
# - analysisDepth: 'module' | 'package' | 'class' | 'function'
# - outputFormat: 'json' | 'dot' | 'mermaid' | 'plantuml'
# - includeMetrics: boolean
```

### Analysis Workflow

1. **Discovery Phase**
   - Identify project structure
   - Detect build configuration
   - Map source directories

2. **Extraction Phase**
   - Parse import/require statements
   - Extract module dependencies
   - Identify external dependencies

3. **Analysis Phase**
   - Calculate coupling metrics
   - Detect architectural patterns
   - Identify violations
   - Map boundaries

4. **Visualization Phase**
   - Generate dependency graphs
   - Create architecture diagrams
   - Produce metric reports

## Output Schema

```json
{
  "analysisId": "string",
  "timestamp": "ISO8601",
  "target": {
    "path": "string",
    "language": "string",
    "moduleCount": "number",
    "totalFiles": "number"
  },
  "architecture": {
    "pattern": "string (layered|modular|monolithic|microservices)",
    "layers": [
      {
        "name": "string",
        "modules": ["string"],
        "allowedDependencies": ["string"]
      }
    ],
    "boundedContexts": [
      {
        "name": "string",
        "modules": ["string"],
        "interfaces": ["string"]
      }
    ]
  },
  "modules": [
    {
      "name": "string",
      "path": "string",
      "files": "number",
      "linesOfCode": "number",
      "dependencies": ["string"],
      "dependents": ["string"],
      "metrics": {
        "afferentCoupling": "number",
        "efferentCoupling": "number",
        "instability": "number",
        "cohesion": "number"
      }
    }
  ],
  "dependencies": [
    {
      "from": "string",
      "to": "string",
      "type": "import|call|inherit|implement",
      "count": "number"
    }
  ],
  "violations": [
    {
      "type": "circular|layer-bypass|abstraction-leak",
      "severity": "high|medium|low",
      "from": "string",
      "to": "string",
      "description": "string",
      "recommendation": "string"
    }
  ],
  "metrics": {
    "averageCoupling": "number",
    "maxCoupling": "number",
    "cyclomaticComplexity": "number",
    "circularDependencies": "number",
    "layerViolations": "number"
  },
  "graphs": {
    "dot": "string (file path)",
    "mermaid": "string (file path)",
    "plantuml": "string (file path)"
  }
}
```

## Integration with Migration Processes

This skill integrates with the following Code Migration/Modernization processes:

- **legacy-codebase-assessment**: Architecture understanding
- **monolith-to-microservices**: Service boundary identification
- **migration-planning-roadmap**: Dependency-based planning
- **code-refactoring**: Coupling reduction targets

## Configuration

### Skill Configuration File

Create `.architecture-analyzer.json` in the project root:

```json
{
  "analysisDepth": "module",
  "excludePaths": [
    "node_modules",
    "vendor",
    "dist",
    "build",
    ".git",
    "__tests__"
  ],
  "modulePatterns": {
    "javascript": "src/*",
    "java": "src/main/java/**",
    "python": "src/*"
  },
  "layers": {
    "enabled": true,
    "definitions": [
      {
        "name": "presentation",
        "patterns": ["**/ui/**", "**/views/**", "**/controllers/**"],
        "allowedDependencies": ["business", "shared"]
      },
      {
        "name": "business",
        "patterns": ["**/services/**", "**/domain/**"],
        "allowedDependencies": ["data", "shared"]
      },
      {
        "name": "data",
        "patterns": ["**/repositories/**", "**/dao/**"],
        "allowedDependencies": ["shared"]
      },
      {
        "name": "shared",
        "patterns": ["**/common/**", "**/utils/**"],
        "allowedDependencies": []
      }
    ]
  },
  "rules": {
    "maxCoupling": 10,
    "maxModuleSize": 5000,
    "forbiddenDependencies": [
      {"from": "presentation", "to": "data"}
    ]
  },
  "visualization": {
    "formats": ["mermaid", "dot"],
    "groupBy": "layer",
    "showMetrics": true
  }
}
```

## MCP Server Integration

When ast-grep MCP Server is available for pattern detection:

```javascript
// Example architecture pattern detection
{
  "tool": "ast_grep_search",
  "arguments": {
    "pattern": "import { $_ } from '../data/$_'",
    "language": "typescript",
    "path": "./src/ui"
  }
}
```

## Architectural Patterns

### Layered Architecture

```
┌─────────────────────────────────┐
│      Presentation Layer         │
│  (UI, Controllers, Views)       │
└──────────────┬──────────────────┘
               │
┌──────────────▼──────────────────┐
│       Business Layer            │
│  (Services, Domain, Logic)      │
└──────────────┬──────────────────┘
               │
┌──────────────▼──────────────────┐
│         Data Layer              │
│  (Repositories, DAOs, ORM)      │
└─────────────────────────────────┘
```

### Modular Monolith

```
┌─────────────────────────────────────────────┐
│              Application Shell               │
├───────────┬───────────┬───────────┬─────────┤
│  Module A │  Module B │  Module C │ Shared  │
│  ┌─────┐  │  ┌─────┐  │  ┌─────┐  │ ┌─────┐ │
│  │ UI  │  │  │ UI  │  │  │ UI  │  │ │Utils│ │
│  ├─────┤  │  ├─────┤  │  ├─────┤  │ └─────┘ │
│  │Logic│  │  │Logic│  │  │Logic│  │         │
│  ├─────┤  │  ├─────┤  │  ├─────┤  │         │
│  │Data │  │  │Data │  │  │Data │  │         │
│  └─────┘  │  └─────┘  │  └─────┘  │         │
└───────────┴───────────┴───────────┴─────────┘
```

### Microservices (Target)

```
┌─────────┐  ┌─────────┐  ┌─────────┐
│Service A│  │Service B│  │Ser