---
name: architecture-enforcer
description: This skill should be used when validating import boundaries and architectural rules in the ISA-Frontend monorepo. It checks for circular dependencies, layer violations (Feature→Feature), domain violations (OMS→Remission), and relative imports. Use this skill when the user wants to check architecture, mentions "validate boundaries", "check imports", or needs dependency analysis.
---

# 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

```bash
# 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

```bash
# 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:**
```bash
# Find feature-to-feature imports
grep -r "from '@isa/[^/]*/feature" libs/*/feature/ --include="*.ts"
```

**Check Relative Imports:**
```bash
# Should use path aliases, not relative
grep -r "from '\.\./\.\./\.\." libs/ --include="*.ts"
```

**Check Direct Swagger Imports:**
```bash
# 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

```bash
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:**
```typescript
// 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:**
```typescript
// Move shared component from feature to ui
// Before: @isa/oms/feature-shared
// After: @isa/ui/order-components
```

**Path Alias Usage:**
```typescript
// 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)
