Purpose

Enforce architectural boundaries and dependency rules across the codebase.

What it checks (8 checks, each with its own script):

1. Core → Domain dependencies (core features cannot depend on domain features)
2. Service imports (services only imported in composition root)
3. Service boundaries (services can only import interfaces/types/config from features)
4. Pages boundaries (pages can only import components/hooks/hocs from features)
5. Model internals encapsulation (cross-feature cannot import model internals)
6. Slice imports (slice.ts only imported in composition root)
7. Sagas imports (sagas.ts only imported in composition root)
8. Circular dependencies (A ↔ B or A → B → C → A)

What it doesn't check:

• Code quality patterns (relative imports, exports, etc.) - see code-audit skill

Architecture Context

This template uses core/domain separation and composition root pattern:

Composition Root (src/config/)

• Top-level wiring layer (NOT a feature)
• Imports services, registers features, defines routes
• ALL architecture rules suspended here

Core Features (src/core/features/)

• Infrastructure: app, auth, components, i18n, layout, router, slice-manager
• Auto-discovered by scanning directory

Domain Features (src/domain/features/)

• Business logic: wallet, oauth, blog-demo, ai-assistant, site
• Auto-discovered by scanning directory
• Users create their own (products, orders, inventory, etc.)

Running Checks

All checks:

node ./.claude/skills/arch-audit/scripts/run_all_checks.mjs

Generate report:

node ./.claude/skills/arch-audit/scripts/generate_report.mjs

Individual checks:

node ./.claude/skills/arch-audit/scripts/check_core_to_domain.mjs
node ./.claude/skills/arch-audit/scripts/check_service_imports.mjs
node ./.claude/skills/arch-audit/scripts/check_service_boundaries.mjs
node ./.claude/skills/arch-audit/scripts/check_pages_boundaries.mjs
node ./.claude/skills/arch-audit/scripts/check_model_internals.mjs
node ./.claude/skills/arch-audit/scripts/check_slice_imports.mjs
node ./.claude/skills/arch-audit/scripts/check_sagas_imports.mjs
node ./.claude/skills/arch-audit/scripts/check_circular_deps.mjs

Architecture Rules

1. Core → Domain Dependencies

RULE: Core features (infrastructure) MUST NOT depend on domain features (business logic).

Allowed:

• ✅ Core → Core (infrastructure can use infrastructure)
• ✅ Domain → Core (business can use infrastructure)

Violations:

• ❌ Core → Domain (infrastructure cannot know about business)

Exception:

• src/config/ is composition root, can import anything

Check: check_core_to_domain.mjs

---

2. Service Imports (Dependency Injection)

RULE: Services (@/services/*) MUST ONLY be imported in composition root (src/config/).

Allowed:

• ✅ src/config/services.ts (root services)
• ✅ src/config/{feature}/services.ts (feature-specific services)

Violations:

• ❌ Any file OUTSIDE src/config/ importing @/services/*

Why: Enforces dependency injection pattern - features receive services through interfaces.

Check: check_service_imports.mjs

---

3. Service Boundaries

RULE: Services can ONLY import interfaces, types, and config from features.

Allowed:

• ✅ @/(core|domain)/features/{feature}/I{Feature}Api.ts (interfaces)
• ✅ @/(core|domain)/features/{feature}/types/* (feature types)
• ✅ @/(core|domain)/features/{feature}/models/{model}/types/* (model types)
• ✅ @/(core|domain)/features/{feature}/config (feature config)
• ✅ @/services/* (other services)
• ✅ External libraries

Violations:

• ❌ @/pages/*
• ❌ @/hooks/*
• ❌ @/(core|domain)/features/{feature}/models/{model}/actions.ts
• ❌ @/(core|domain)/features/{feature}/models/{model}/slice.ts
• ❌ @/(core|domain)/features/{feature}/models/{model}/actionEffects/*
• ❌ @/(core|domain)/features/{feature}/hooks/*
• ❌ @/(core|domain)/features/{feature}/components/*

Why: Services implement interfaces - they work with data contracts (interfaces + types + config), not implementation details.

Check: check_service_boundaries.mjs

---

4. Pages Boundaries

RULE: Pages can ONLY import presentation layer (components, hooks, hocs) from features.

Allowed:

• ✅ @/(core|domain)/features/{feature}/components/*
• ✅ @/(core|domain)/features/{feature}/hooks/*
• ✅ @/(core|domain)/features/{feature}/hocs/*
• ✅ @/(core|domain)/features/{feature}/config
• ✅ @/hooks/* (root hooks)
• ✅ External libraries

Violations:

• ❌ @/services/*
• ❌ @/(core|domain)/features/{feature}/models/*
• ❌ @/(core|domain)/features/{feature}/types/*
• ❌ @/(core|domain)/features/{feature}/slice.ts
• ❌ @/(core|domain)/features/{feature}/sagas.ts
• ❌ @/(core|domain)/features/{feature}/I{Feature}Api.ts

Why: Pages are presentation layer - they orchestrate UI, not business logic. All business logic should be in feature hooks.

Check: check_pages_boundaries.mjs

---

5. Model Internals Encapsulation

RULE: Cross-feature imports CANNOT access model internals (actions, slice, actionEffects).

Allowed (cross-feature):

• ✅ @/(core|domain)/features/{feature}/models/{model}/types/* (types only)
• ✅ @/(core|domain)/features/{feature}/hooks/* (feature hooks)
• ✅ @/(core|domain)/features/{feature}/components/*
• ✅ @/(core|domain)/features/{feature}/hocs/*

Violations (cross-feature):

• ❌ @/(core|domain)/features/{feature}/models/{model}/actions.ts
• ❌ @/(core|domain)/features/{feature}/models/{model}/slice.ts
• ❌ @/(core|domain)/features/{feature}/models/{model}/actionEffects/*
• ❌ @/(core|domain)/features/{feature}/models/{model}/IModelApi.ts

Why: Models are private implementation details. Features expose APIs through hooks, not direct model access.

Note: Within same feature, you can import model internals freely.

Check: check_model_internals.mjs

---

6. Slice Import Restriction

RULE: Feature slice.ts files MUST ONLY be imported in src/config/features.ts.

Allowed:

• ✅ src/config/features.ts

Violations:

• ❌ Any other file importing @/(core|domain)/features/{feature}/slice

Why: Slices are registered in composition root for Redux store setup.

Check: check_slice_imports.mjs

---

7. Sagas Import Restriction

RULE: Feature sagas.ts files MUST ONLY be imported in src/config/features.ts.

Allowed:

• ✅ src/config/features.ts

Violations:

• ❌ Any other file importing @/(core|domain)/features/{feature}/sagas

Why: Sagas are registered in composition root for Redux Saga middleware setup.

Check: check_sagas_imports.mjs

---

8. Circular Dependencies

RULE: Module dependencies must form a DAG (Directed Acyclic Graph). No circular imports.

Detected:

• Direct cycles: A ↔ B
• Deep cycles: A → B → C → A

Why: Circular dependencies cause bundling issues, hard to understand, difficult to test.

Check: check_circular_deps.mjs

---

Architecture Layers

┌──────────────────────────────────────────┐
│  Composition Root (src/config/)          │ ← Wires everything together
├──────────────────────────────────────────┤
│  Core Features (src/core/features/)      │ ← Infrastructure
│  Domain Features (src/domain/features/)  │ ← Business Logic
├──────────────────────────────────────────┤
│  Service Layer (src/services/)           │ ← External integrations
└──────────────────────────────────────────┘

Benefits:

• Clear separation of concerns
• Core infrastructure doesn't know about business domains
• Easy to swap implementations (dependency injection)
• Features properly encapsulated

Output Format

Each check reports:

• File paths and line numbers of violations
• What's wrong
• How to fix it
• Violation count
• Exit code 0 (success) or 1 (failures)

Reports are saved to reports/{date}/arch-audit-report.md when using generate_report.mjs.

Tools

• Bash: Run Node.js scripts
• Read: Inspect source files
• Write: Generate reports (optional)

Safety

• Read-only operation (unless generating reports)
• No source file modifications
• No external network calls
• Comprehensive dependency analysis