Agent skill

architecture-analyzer

Analyze and visualize software architecture patterns, dependencies, and module boundaries for migration planning

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/code-migration-modernization/skills/architecture-analyzer

SKILL.md

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│  │Service C│
│  ┌───┐  │  │  ┌───┐  │  │  ┌───┐  │
│  │API│  │  │  │API│  │  │  │API│  │
│  └─┬─┘  │  │  └─┬─┘  │  │  └─┬─┘  │
│    │    │  │    │    │  │    │    │
│  ┌─▼─┐  │  │  ┌─▼─┐  │  │  ┌─▼─┐  │
│  │DB │  │  │  │DB │  │  │  │DB │  │
│  └───┘  │  │  └───┘  │  │  └───┘  │
└─────────┘  └─────────┘  └─────────┘
      │            │            │
      └────────────┼────────────┘
                   │
            ┌──────▼──────┐
            │  Event Bus  │
            └─────────────┘

Metrics Reference

Coupling Metrics

Metric Formula Good Warning Bad
Afferent Coupling (Ca) Incoming dependencies < 10 10-20 > 20
Efferent Coupling (Ce) Outgoing dependencies < 10 10-20 > 20
Instability (I) Ce / (Ca + Ce) 0-0.3 or 0.7-1.0 0.3-0.7 -
Abstractness (A) Abstract classes / Total Context dependent - -

Distance from Main Sequence

D = |A + I - 1|

  • D = 0: Ideal (on the main sequence)
  • D > 0.3: Warning
  • D > 0.5: Problematic

Best Practices

  1. Regular Analysis: Run architecture analysis as part of CI/CD
  2. Define Boundaries: Explicitly define module and layer boundaries
  3. Enforce Rules: Use architectural fitness functions
  4. Document Decisions: Use ADRs for architectural changes
  5. Track Metrics: Monitor coupling trends over time
  6. Visualize: Keep architecture diagrams up to date

Related Skills

  • static-code-analyzer: Code-level analysis
  • domain-model-extractor: DDD boundary identification
  • technical-debt-quantifier: Architecture debt assessment

Related Agents

  • legacy-system-archaeologist: Uses this skill for architecture discovery
  • microservices-decomposer: Uses this skill for boundary identification
  • ddd-analyst: Uses this skill for context mapping
  • migration-readiness-assessor: Uses this skill for architecture evaluation

References

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31
Explore
a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31
Explore
a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31
Explore
a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31
Explore
a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31
Explore
a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results