architecture-analyzer

---

name: architecture-analyzer description: Analyze software architecture and dependencies using SciTools Understand. Detect circular dependencies, tight coupling, architectural violations, and layer issues directly via und reports and queries. argument-hint: [target] [analysis-type] allowed-tools: Bash(und *), Read, Grep, Glob, Write

Software Architecture and Dependency Analyzer

You are an expert in software architecture analysis using SciTools Understand (und). Analyze dependencies and architecture directly through und commands - export only when specifically requested.

Core Analysis Workflow

Step 1: Database Setup (if needed)

# Check for existing database
ls -la *.und 2>/dev/null

# Create new database
und create -db arch_analysis.und -local -languages $LANGUAGES
und add $SOURCE_DIR arch_analysis.und
und analyze arch_analysis.und

Step 2: Analyze Dependencies Directly

# View file structure with dependencies
und list -tree files $DATABASE

# Show dependencies for specific file
und list -file path/to/file.c settings $DATABASE

# Get metrics for complexity analysis
und metrics -summary $DATABASE

# Architecture metrics
und metrics -arch "Directory Structure" $DATABASE

Dependency Analysis via Reports

Find High Fan-Out (Complex Dependencies)

Use dependency reports grouped by source:

# Show files with most outgoing dependencies
und export -dependencies -group from file csv fan_out.csv $DATABASE
head -20 fan_out.csv  # Show top 20

# Or use HTML report
und metrics -html $DATABASE
# Check archname_metrics/ for dependency visualization

What to look for:

• Files with >20 outgoing dependencies need refactoring
• Compare with complexity metrics (Cyclomatic)

Find High Fan-In (Widely Used Files)

# Show files most depended upon
und export -dependencies -group to file csv fan_in.csv $DATABASE
head -20 fan_in.csv

# These are stable/core components - should have low complexity

Interpretation:

• High fan-in + high complexity = brittle core (refactor priority)
• High fan-in + low complexity = good abstraction

Detect Circular Dependencies

# Export dependency data for cycle detection
und export -dependencies file csv deps.csv $DATABASE

# Check for bidirectional dependencies
und export -dependencies -col refs,froments,toents file csv bidirectional.csv $DATABASE

# Look for same file pair in both directions
awk -F',' '{print $1","$2}' bidirectional.csv | sort | uniq -d

Or use architecture reports:

# Generate dependency report
und report "Dependency Browser" $DATABASE
# Use interactive browser to trace cycles

Check Layer Violations

# Export with short format to see directory-level dependencies
und export -dependencies -format short file csv layers.csv $DATABASE

# Check for violations (example: ui -> data)
grep "ui/.*data/" layers.csv

# Group by source directory
und export -dependencies -group from -format short file csv by_dir.csv $DATABASE

Common violations to check:

• ui/ → data/ (should go through service layer)
• util/ → domain/ (utilities shouldn't depend on domain)
• infrastructure/ → ui/ (infra shouldn't depend on presentation)

Architecture-Level Analysis

# List all architectures
und list arches $DATABASE

# Get metrics for specific architecture
und metrics -arch "Directory Structure" $DATABASE

# Export architecture dependencies
und export -dependencies arch "Directory Structure" csv arch_deps.csv $DATABASE

Direct Analysis Commands

Analyze Specific File Dependencies

# Show what a file depends on
und export -dependencies file csv specific.csv $DATABASE | grep "From File.*my_file.c"

# Show what depends on a file
und export -dependencies file csv specific.csv $DATABASE | grep "To File.*my_file.c"

Compile-Time vs Link-Time

# Compile-time (include dependencies)
und export -dependencies -mode compile file csv compile.csv $DATABASE

# Link-time (default)
und export -dependencies file csv link.csv $DATABASE

# Compare to find differences
diff compile.csv link.csv

Class/Entity Level Analysis

# Class dependency matrix
und export -dependencies class matrix classes.csv $DATABASE

# Entity-level dependencies for specific file
und export -dependencies -col froments,toents file csv entities.csv $DATABASE | grep "my_file"

Focused Reports

Complexity + Dependency Hotspots

# Get complexity metrics
und metrics -summary $DATABASE > complexity.txt

# Get dependency counts
und export -dependencies -group from file csv fanout.txt $DATABASE

# Cross-reference to find problems:
# High complexity + high fan-out = refactoring candidate

Architecture Health Summary

# Generate comprehensive HTML report
und metrics -html $DATABASE

# Check key indicators:
# - Circular dependencies (should be 0)
# - Max fan-out (should be <20)
# - Architecture instability metrics

Dependency Rules Validation

# Export all dependencies for rule checking
und export -dependencies file csv all_deps.csv $DATABASE

# Check specific rules:
# No dependencies from ui to data
grep "^ui.*/,.*data/" all_deps.csv

# No dependencies from tests to production (reverse)
grep "^test.*/,.*src/" all_deps.csv

Architecture Comparison

Compare Two Architectures

# Metrics comparison
und metrics -arch "Architecture A" metrics_a.csv $DATABASE
und metrics -arch "Architecture B" metrics_b.csv $DATABASE

# Dependency comparison
und export -dependencies arch "Architecture A" csv deps_a.csv $DATABASE
und export -dependencies arch "Architecture B" csv deps_b.csv $DATABASE

Compare Database Versions

# Create comparison database
und create -db new.und -refdb old.und -gitcommit $COMMIT -languages $LANG
und add src/ new.und
und analyze new.und

# Export changed dependencies
und export -changes -columns "Long Name,Kind Long Name,CountLineNew,CountLineChanged" changed.csv new.und

Interactive Analysis

Use Understand's Interactive Reports

# Launch interactive mode
und $DATABASE

# Interactive commands:
> list -tree files        # File tree
> list -all settings      # Show all settings
> metrics                 # Show metrics
> help report             # Available reports

Generate Visual Reports

# Project Browser (interactive HTML)
und report "Project Browser" project_browser.html $DATABASE

# Dependency Browser
und report "Dependency Browser" deps.html $DATABASE

# Entity report by file
und report "Entity By File" entities.html $DATABASE

Common Analysis Tasks

Task 1: Quick Architecture Health Check

# 1. Check structure
und list -tree files $DATABASE | head -50

# 2. Get metrics summary
und metrics -summary $DATABASE

# 3. Check for obvious issues
und export -dependencies -group from file csv check.csv $DATABASE
head -5 check.csv  # Show highest fan-out

# 4. Generate HTML report
und metrics -html $DATABASE

Task 2: Find Refactoring Candidates

# High complexity files
und metrics -summary $DATABASE | grep "Cyclomatic"

# High dependency files
und export -dependencies -group from file csv candidates.csv $DATABASE

# Cross-reference: look for files appearing in both

Task 3: Validate Layer Architecture

# Export short-format dependencies
und export -dependencies -format short file csv validate.csv $DATABASE

# Check layer rules
grep "^ui.*/,.*data/" validate.csv      # ui -> data (BAD)
grep "^service.*/,.*ui/" validate.csv   # service -> ui (BAD)

Task 4: Detect Circular Dependencies

# Export all file dependencies
und export -dependencies file csv cycles.csv $DATABASE

# Find bidirectional (same pair reversed)
awk -F',' '{print $1","$2}' cycles.csv | sort | uniq -c | sort -rn | head -20

Task 5: Module Boundary Analysis

# See dependencies grouped by target
und export -dependencies -group to file csv boundaries.csv $DATABASE

# High counts = heavily used modules (good candidates for extraction)

Metrics Interpretation

Dependency Health Indicators

Indicator	Good	Warning	Critical
Max fan-out	<10	10-20	>20
Bidirectional deps	0	<5	>5
Layer violations	0	<10	>10
Cycles	0	0	>0

Complexity + Dependency Matrix

Low Complexity	High Complexity
Low Fan-Out	Good
High Fan-In	Good abstraction
Low Fan-In	Leaf node

Architecture Patterns

Good indicators:

• Acyclic dependency graph
• Clear layer separation
• Unidirectional dependencies
• Low coupling between layers

Bad indicators:

• Circular dependencies
• Bidirectional layer links
• God objects (high fan-in + fan-out)
• Skyhook dependencies (skip layers)

Report Output Options

CSV Export (when needed)

# Minimal - for quick checks
und export -dependencies -col refs -format short file csv minimal.csv $DATABASE

# Full - for detailed analysis
und export -dependencies -col all file csv full.csv $DATABASE

# Grouped - for summaries
und export -dependencies -group to file csv summary.csv $DATABASE

HTML Reports

# Metrics with visualization
und metrics -html $DATABASE

# Interactive browsers
und report "Project Browser" browser.html $DATABASE
und report "Dependency Browser" deps.html $DATABASE

Text/Console Output

# Summary to stdout
und metrics -summary $DATABASE

# Tree view
und list -tree files $DATABASE

# Settings
und list -all settings $DATABASE

Quick Reference

# Structure
und list -tree files $DATABASE

# Dependencies (minimal output)
und export -dependencies -col refs -format short file csv quick.csv $DATABASE

# High fan-out
und export -dependencies -group from file csv fanout.csv $DATABASE

# High fan-in
und export -dependencies -group to file csv fanin.csv $DATABASE

# Metrics
und metrics -summary $DATABASE
und metrics -html $DATABASE

# Architecture
und metrics -arch "Directory Structure" $DATABASE
und list arches $DATABASE

# HTML Reports
und report "Project Browser" index.html $DATABASE

Best Practices

1. Use HTML reports for visual analysis - better than raw CSV
2. Start with metrics summary before deep diving
3. Group exports (-group from/to) to reduce output size
4. Filter with grep instead of exporting everything
5. Use architectures to analyze subsystems independently
6. Interactive mode (und $DATABASE) for exploration

Additional Resources

• For a quick introduction, see README.md
• For detailed example prompts, see examples.md
• For und command reference, use the scitools-understand skill