component-boundary-identifier

name

component-boundary-identifier

description

Identifies boundaries between modules or components in software systems through static code analysis and dependency detection. Use when Claude needs to analyze software architecture, identify module boundaries, detect boundary violations, find circular dependencies, or assess component coupling. Supports Python (packages and imports) and Java (packages and dependencies). Trigger when users ask to "identify boundaries", "find component boundaries", "detect boundary violations", "analyze module structure", "check architecture", or "find circular dependencies".

Component Boundary Identifier

Identify and analyze boundaries between software components to ensure proper architectural separation.

Quick Start

When a user requests boundary analysis:

1. Understand the goal: Identify boundaries, detect violations, or both
2. Analyze structure: Examine package/module organization and dependencies
3. Identify boundaries: Determine component boundaries based on structure
4. Detect violations: Find improper cross-boundary dependencies
5. Report findings: Present boundaries and violations with severity levels

What This Skill Does

Boundary Identification

Identify component boundaries based on:

• Package/module structure
• Namespace organization
• Architectural patterns (layered, hexagonal, clean)
• Naming conventions
• Dependency clusters

Violation Detection

Detect boundary violations including:

• Upward dependencies (lower layers depending on higher layers)
• Circular dependencies between components
• Layer skipping (bypassing intermediate layers)
• Domain depending on infrastructure
• Accessing private/internal implementations
• Concrete type dependencies across boundaries

Analysis Methods

Static Code Analysis

Analyze code structure without execution.

Python:

• Parse import statements
• Analyze package structure
• Identify dependency directions
• Detect circular imports

Java:

• Parse import statements
• Analyze package hierarchy
• Check access modifiers
• Identify dependency directions

Script: Use scripts/analyze_boundaries.py for automated Python analysis

Manual Code Review

Review code for boundary patterns.

Process:

1. Identify top-level packages/modules
2. Map dependencies between components
3. Check against architectural rules
4. Find violations

See: boundary-indicators.md for patterns

Architectural Patterns

Layered Architecture

Layers (top to bottom):

1. Presentation/API
2. Application/Service
3. Domain/Business
4. Infrastructure/Data

Rules:

• Dependencies flow downward only
• No layer skipping
• No upward dependencies

Violations:

• Domain imports from API
• Infrastructure imports from Domain
• API directly uses Infrastructure (skips Service)

Hexagonal Architecture

Boundaries:

• Core: Domain logic (center)
• Ports: Interfaces for external interaction
• Adapters: Implementations (outside)

Rules:

• Core has no dependencies on adapters
• Adapters depend on ports
• All external access through ports

Violations:

• Core imports adapter implementations
• Core depends on frameworks
• Direct adapter-to-adapter dependencies

Clean Architecture

Boundaries (inside to outside):

1. Entities (domain models)
2. Use Cases (business rules)
3. Interface Adapters
4. Frameworks & Drivers

Dependency Rule:

• Dependencies point inward only
• Inner layers independent of outer layers

Violations:

• Inner layer imports outer layer
• Domain depends on UI/API
• Use cases depend on frameworks

Language-Specific Guidance

Python

Boundary indicators:

• Top-level packages (domain/, infrastructure/, api/)
• __init__.py with controlled exports
• Protocol/ABC definitions

Common violations:

• Domain imports from infrastructure
• Circular imports between modules
• Importing private members (_name)
• Direct implementation dependencies

See: boundary-indicators.md for details

Java

Boundary indicators:

• Package hierarchy (com.example.domain, com.example.infrastructure)
• Access modifiers (public, package-private, private)
• Interface definitions

Common violations:

• Domain imports infrastructure packages
• Accessing package-private from different package
• Static coupling across boundaries
• Framework annotations in domain

See: boundary-indicators.md for details

Workflow

1. Understand the Request

Questions to clarify:

• Identify boundaries or detect violations?
• Specific architectural pattern in use?
• Focus on specific components?
• Known problem areas?

2. Analyze Project Structure

For automated analysis:

python scripts/analyze_boundaries.py <project_directory>

For manual analysis:

1. List top-level packages/modules
2. Identify architectural layers
3. Note naming conventions
4. Understand intended architecture

3. Identify Boundaries

Look for:

• Package/module groupings
• Architectural layer separation
• Domain vs infrastructure separation
• API vs business logic separation

Document:

• Boundary names and purposes
• Components within each boundary
• Intended dependency directions

4. Detect Violations

Check for:

• Upward dependencies
• Circular dependencies
• Layer skipping
• Concrete type dependencies
• Private/internal access

See: violation-patterns.md for patterns

5. Report Findings

Structure:

IDENTIFIED BOUNDARIES
- boundary1/ (N modules)
- boundary2/ (M modules)

BOUNDARY VIOLATIONS
[CRITICAL] module_a depends on higher layer module_b
[HIGH] Circular dependency: module_c -> module_d -> module_c
[MEDIUM] module_e accesses private implementation

RECOMMENDATIONS
- Fix critical violations first
- Introduce interfaces for concrete dependencies
- Refactor circular dependencies

Violation Severity Levels

Critical

• Domain depends on infrastructure
• Upward dependencies in layered architecture
• Circular dependencies between major components

Impact: Breaks architectural principles, prevents proper separation

Priority: Fix immediately

High

• Layer skipping
• Concrete type dependencies across boundaries
• Framework coupling in domain

Impact: Reduces flexibility, complicates testing

Priority: Fix soon

Medium

• Accessing private/internal members
• Static coupling across boundaries
• Missing interfaces at boundaries

Impact: Breaks encapsulation, reduces maintainability

Priority: Fix when refactoring

Low

• Suboptimal package structure
• Inconsistent naming
• Missing documentation

Impact: Reduces code clarity

Priority: Fix opportunistically

Detection Patterns

Upward Dependency

Pattern:

# domain/services.py
from api.serializers import UserSerializer  # VIOLATION

Detection: Lower layer imports from higher layer

Fix: Move serialization to API layer

Circular Dependency

Pattern:

# module_a.py
from module_b import ClassB

# module_b.py
from module_a import ClassA  # VIOLATION

Detection: A imports B, B imports A

Fix: Extract shared interface, use dependency injection

Layer Skipping

Pattern:

# api/routes.py
from infrastructure.repositories import UserRepository  # VIOLATION

Detection: API directly uses infrastructure (skips service layer)

Fix: Use service layer as intermediary

Concrete Dependency

Pattern:

# domain/services.py
from infrastructure.email import SMTPEmailSender  # VIOLATION

class NotificationService:
    def __init__(self):
        self.sender = SMTPEmailSender()

Detection: Domain depends on concrete infrastructure class

Fix: Depend on interface, inject implementation

Best Practices

Boundary Definition

• Use clear package/module names
• Follow architectural patterns consistently
• Document boundary purposes
• Establish dependency rules

Dependency Management

• Depend on interfaces, not implementations
• Use dependency injection
• Follow dependency inversion principle
• Avoid static coupling

Violation Prevention

• Code reviews focusing on imports
• Automated dependency analysis in CI/CD
• Architecture decision records
• Team training on patterns

Refactoring Strategy

• Fix critical violations first
• Introduce interfaces gradually
• Extract shared code carefully
• Test after each change

Example Usage Patterns

User: "Identify the component boundaries in this codebase" → Analyze structure, identify boundaries, report findings

User: "Check if there are any boundary violations" → Analyze dependencies, detect violations, report with severity

User: "Is my domain layer properly isolated?" → Check domain dependencies, verify no infrastructure/API imports

User: "Find circular dependencies in the project" → Analyze import graph, identify cycles, report

User: "Does this follow clean architecture?" → Identify layers, check dependency directions, report violations

User: "Why is this module hard to test?" → Analyze dependencies, identify concrete couplings, suggest fixes

Automated Analysis

Use the provided script for Python projects:

python scripts/analyze_boundaries.py /path/to/project

Output:

• Identified boundaries
• Boundary violations with severity
• Circular dependencies
• Recommendations

Limitations:

• Python only (for automated analysis)
• Requires valid Python syntax
• May miss dynamic imports
• Heuristic-based layer detection

For Java or manual analysis, follow the workflow using reference patterns.