ISA-Frontend/.claude/skills/architecture-enforcer/SKILL.md

name, description

name	description
architecture-enforcer	This skill should be used when checking architecture compliance, validating layer boundaries (Feature→Feature violations), detecting circular dependencies, or user mentions "check architecture", "validate boundaries", "check imports". Validates import boundaries and architectural rules in ISA-Frontend monorepo.

Architecture Enforcer

Overview

Validate and enforce architectural boundaries in the monorepo. Checks import rules, detects violations, generates dependency graphs, and suggests refactoring.

When to Use This Skill

Invoke when user wants to:

• Validate import boundaries
• Check architectural rules
• Find dependency violations
• Mentioned "check architecture" or "validate imports"

Architectural Rules

✅ Allowed:

• Feature → Data Access
• Feature → UI
• Feature → Util
• Data Access → Util

❌ Forbidden:

• Feature → Feature
• Data Access → Feature
• UI → Feature
• Cross-domain (OMS ↔ Remission)

Enforcement Workflow

Step 1: Run Nx Dependency Checks

# Lint all (includes boundary checks)
npx nx run-many --target=lint --all

# Or specific library
npx nx lint [library-name]

Step 2: Generate Dependency Graph

# Visual graph
npx nx graph

# Focus on specific project
npx nx graph --focus=[library-name]

# Affected projects
npx nx affected:graph

Step 3: Scan for Violations

Check for Circular Dependencies: Use Explore agent to find A→B→A patterns.

Check Layer Violations:

# Find feature-to-feature imports
grep -r "from '@isa/[^/]*/feature" libs/*/feature/ --include="*.ts"

Check Relative Imports:

# Should use path aliases, not relative
grep -r "from '\.\./\.\./\.\." libs/ --include="*.ts"

Check Direct Swagger Imports:

# Should go through data-access
grep -r "from '@generated/swagger" libs/*/feature/ --include="*.ts"

Step 4: Categorize Violations

🔴 Critical:

• Circular dependencies
• Feature → Feature
• Data Access → Feature
• Cross-domain dependencies

⚠️ Warnings:

• Relative imports (should use aliases)
• Missing tags in project.json
• Deep import paths

ℹ️ Info:

• Potential shared utilities

Step 5: Generate Violation Report

For each violation:

📍 libs/oms/feature/return-search/src/lib/component.ts:12
🔴 Layer Violation
❌ Feature importing from another feature

Import: import { OrderList } from '@isa/oms/feature-order-list';
Issue: Feature libraries should not depend on other features
Fix: Move shared component to @isa/shared/* or @isa/ui/*

Step 6: Suggest Refactoring

For repeated patterns:

• Create shared library for common components
• Extract shared utilities to util library
• Move API clients to data-access layer
• Create facade services

Step 7: Visualize Problems

npx nx graph --focus=[problematic-library]

Step 8: Generate Report

Import Boundary Analysis
========================

Scope: [All | Specific library]

📊 Summary
----------
Total violations: XX
🔴 Critical: XX
⚠️ Warnings: XX
ℹ️ Info: XX

🔍 Violations by Type
---------------------
Layer violations: XX
Domain violations: XX
Circular dependencies: XX
Path alias violations: XX

🔴 Critical Violations
----------------------
1. [File:Line]
   Issue: Feature → Feature dependency
   Fix: Extract to @isa/shared/component-name

2. [File:Line]
   Issue: Circular dependency
   Fix: Extract interface to util library

💡 Refactoring Recommendations
-------------------------------
1. Create @isa/shared/order-components
   - Move: [list of shared components]
   - Benefits: Reusable, breaks circular deps

2. Extract interfaces to @isa/oms/util
   - Move: [list of interfaces]
   - Benefits: Breaks circular dependencies

📈 Dependency Graph
-------------------
npx nx graph --focus=[library]

🎯 Next Steps
-------------
1. Fix critical violations
2. Update ESLint config
3. Refactor shared components
4. Re-run: architecture-enforcer

Common Fixes

Circular Dependencies:

// Extract shared interface to util
// @isa/oms/util
export interface OrderId { id: string; }

// Both services import from util
import { OrderId } from '@isa/oms/util';

Layer Violations:

// Move shared component from feature to ui
// Before: @isa/oms/feature-shared
// After: @isa/ui/order-components

Path Alias Usage:

// BEFORE: import { Service } from '../../../data-access/src/lib/service';
// AFTER: import { Service } from '@isa/oms/data-access';

References

• CLAUDE.md Architecture section
• Nx enforce-module-boundaries: https://nx.dev/nx-api/eslint-plugin/documents/enforce-module-boundaries
• tsconfig.base.json (path aliases)