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.