ISA-Frontend/docs/dependency-hierarchy.md

ISA-Frontend: Dependency Hierarchy Diagram

1. Layer-Based Dependency Model

Level 4: Feature Components (Entry Points)
├── oms-feature-return-search
├── oms-feature-return-details
├── oms-feature-return-process
├── oms-feature-return-summary
├── oms-feature-return-review
├── remission-feature-remission-list
├── remission-feature-remission-return-receipt-list
├── remission-feature-remission-return-receipt-details
├── checkout-feature-reward-catalog
├── checkout-feature-reward-shopping-cart
└── checkout-feature-reward-order-confirmation

Level 3: Shared & UI Components
├── OMS Shared
│   ├── oms-shared-product-info
│   └── oms-shared-task-list
├── Remission Shared
│   ├── remission-shared-product
│   ├── remission-shared-remission-start-dialog
│   ├── remission-shared-return-receipt-actions
│   └── remission-shared-search-item-to-remit-dialog
├── Checkout Shared
│   ├── checkout-shared-product-info
│   └── checkout-shared-reward-selection-dialog
└── UI Component Library (17)
    ├── ui-buttons
    ├── ui-input-controls
    ├── ui-dialog
    ├── ui-datepicker
    ├── ui-layout
    ├── ui-menu
    ├── ui-toolbar
    ├── ui-search-bar
    ├── ui-expandable
    ├── ui-empty-state
    ├── ui-skeleton-loader
    ├── ui-carousel
    ├── ui-item-rows
    ├── ui-progress-bar
    ├── ui-tooltip
    ├── ui-label
    └── ui-bullet-list

Level 2: Data Access Layer
├── oms-data-access
├── remission-data-access
├── checkout-data-access
├── catalogue-data-access
├── availability-data-access
└── crm-data-access

Level 1: Infrastructure & Core
├── Core Libraries (5)
│   ├── core-config
│   ├── core-logging
│   ├── core-navigation
│   ├── core-storage
│   └── core-tabs
├── Common Utilities (3)
│   ├── common-data-access
│   ├── common-decorators
│   └── common-print
├── Shared Components (7)
│   ├── shared-address
│   ├── shared-filter
│   ├── shared-product-image
│   ├── shared-product-format
│   ├── shared-product-router-link
│   ├── shared-quantity-control
│   └── shared-scanner
├── Generated APIs (10)
│   ├── @generated/swagger/oms-api
│   ├── @generated/swagger/checkout-api
│   ├── @generated/swagger/crm-api
│   ├── @generated/swagger/cat-search-api
│   ├── @generated/swagger/availability-api
│   ├── @generated/swagger/isa-api
│   ├── @generated/swagger/eis-api
│   ├── @generated/swagger/inventory-api
│   ├── @generated/swagger/print-api
│   └── @generated/swagger/wws-api
└── Utilities (3)
    ├── utils-ean-validation
    ├── utils-scroll-position
    └── utils-z-safe-parse

---

2. OMS Domain Dependency Tree

oms-feature-return-search
├── oms-data-access
│   ├── @generated/swagger/oms-api
│   ├── @generated/swagger/print-api
│   ├── @isa/core/logging
│   └── @isa/common/data-access
├── oms-shared-product-info
│   ├── shared-product-image
│   ├── shared-product-format
│   ├── ui-item-rows
│   └── ui-label
└── ui-* (search-bar, buttons, empty-state, etc.)

oms-feature-return-details
├── oms-data-access (store)
├── oms-shared-product-info
├── ui-input-controls (quantity selector)
├── ui-buttons
└── shared-quantity-control

oms-feature-return-process
├── oms-data-access (update store)
├── ui-input-controls (forms)
├── ui-buttons
└── common-data-access (validation)

oms-feature-return-summary
├── oms-data-access (confirmation)
├── oms-shared-product-info
├── oms-shared-task-list
├── common-print (printing)
└── ui-buttons

oms-feature-return-review
├── oms-data-access (state)
├── oms-shared-product-info
├── common-print (reprint)
└── ui-empty-state

---

3. Remission Domain Dependency Tree

remission-feature-remission-list
├── remission-data-access
│   ├── @generated/swagger/remission-api
│   ├── @isa/core/logging
│   └── @isa/common/data-access
├── remission-shared-remission-start-dialog
├── ui-dialog
├── ui-buttons
└── shared-filter

remission-feature-remission-return-receipt-list
├── remission-data-access
├── remission-shared-search-item-to-remit-dialog
├── remission-shared-return-receipt-actions
├── ui-buttons
└── ui-empty-state

remission-feature-remission-return-receipt-details
├── remission-data-access
├── remission-shared-product
│   ├── shared-product-image
│   ├── shared-product-format
│   └── ui-item-rows
├── remission-shared-return-receipt-actions
├── ui-expandable
└── ui-buttons

---

4. Checkout Domain Dependency Tree

checkout-feature-reward-shopping-cart
├── checkout-data-access
│   ├── @generated/swagger/checkout-api
│   ├── @generated/swagger/crm-api
│   ├── @isa/core/logging
│   └── @isa/common/data-access
├── checkout-shared-product-info
│   ├── shared-product-image
│   └── ui-item-rows
├── checkout-shared-reward-selection-dialog
├── shared-quantity-control
├── ui-buttons
└── ui-empty-state

checkout-feature-reward-catalog
├── checkout-data-access
├── checkout-shared-product-info
├── shared-product-image
├── ui-buttons
├── ui-carousel
└── ui-skeleton-loader

checkout-feature-reward-order-confirmation
├── checkout-data-access
├── checkout-shared-product-info
├── ui-buttons
└── shared-address

---

5. Complete Cross-Domain Dependency Matrix

Domain              → Depends On
────────────────────────────────
OMS Features        → oms-data-access, oms-shared-*, ui-*, shared-*
OMS Data Access     → @generated/swagger/*, core-*, common-*
Remission Features  → remission-data-access, remission-shared-*, ui-*, shared-*
Remission D.A.      → @generated/swagger/*, core-*, common-*
Checkout Features   → checkout-data-access, checkout-shared-*, ui-*, shared-*
Checkout D.A.       → @generated/swagger/*, core-*, common-*
Catalogue D.A.      → @generated/swagger/*, core-*, common-*
Availability D.A.   → @generated/swagger/*, core-*, common-*
CRM D.A.            → @generated/swagger/crm-api, core-*, common-*
UI Components       → core-config, common-*, no data-access deps
Shared Components   → core-*, ui-*, no data-access deps
Core Libraries      → No monorepo dependencies
Common Libraries    → core-*, no domain deps
Generated APIs      → External (backend)
Utilities           → core-config, no domain deps

---

6. Import Path Conventions

All imports follow strict path aliases:

// Domain-specific data-access
import { OrderStore, orderStore } from '@isa/oms/data-access';
import { ReturnStore, returnStore } from '@isa/remission/data-access';
import { CartStore, cartStore } from '@isa/checkout/data-access';

// Domain-specific shared components
import { OmsProductInfo } from '@isa/oms/shared/product-info';
import { RemissionProduct } from '@isa/remission/shared/product';
import { CheckoutProductInfo } from '@isa/checkout/shared/product-info';

// UI component library
import { UiButton, UiPrimaryButton } from '@isa/ui/buttons';
import { UiDialog } from '@isa/ui/dialog';
import { UiEmptyState } from '@isa/ui/empty-state';

// Shared components
import { SharedAddress } from '@isa/shared/address';
import { SharedFilter } from '@isa/shared/filter';
import { SharedProductImage } from '@isa/shared/product-image';

// Core infrastructure
import { Config } from '@isa/core/config';
import { logger } from '@isa/core/logging';
import { navigationState } from '@isa/core/navigation';
import { storageProvider } from '@isa/core/storage';
import { tabManager } from '@isa/core/tabs';

// Common utilities
import { tapResponse } from '@isa/common/data-access';
import { Cached, Debounce } from '@isa/common/decorators';
import { PrintService } from '@isa/common/print';

// General utilities
import { validateEan } from '@isa/utils/ean-validation';
import { restoreScrollPosition } from '@isa/utils/scroll-position';
import { safeParse } from '@isa/utils/z-safe-parse';

// Generated Swagger APIs
import { OmsApiClient } from '@generated/swagger/oms-api';
import { CheckoutApiClient } from '@generated/swagger/checkout-api';
import { CrmApiClient } from '@generated/swagger/crm-api';

---

7. NO Circular Dependencies

The architecture enforces strict acyclic dependencies:

Feature Layer (Level 4)
   ↓ (one-way only)
Shared/UI Layer (Level 3)
   ↓ (one-way only)
Data Access Layer (Level 2)
   ↓ (one-way only)
Infrastructure Layer (Level 1)
   ↓ (one-way only)
External APIs & Services (Backend)

Verification Command:

npx nx affected:lint --skip-nx-cache

---

8. Bundle Dependency Impact

Smallest Dependencies (Infrastructure)

• core-config (~2KB)
• core-logging (~5KB)
• utils-ean-validation (~3KB)

Medium Dependencies (Shared)

• shared-product-image (~8KB)
• ui-buttons (~12KB)
• ui-input-controls (~20KB)

Larger Dependencies (Domain)

• oms-data-access (~25KB including API client)
• checkout-data-access (~30KB including API client)
• remission-data-access (~20KB including API client)

Impact on Main Bundle

• All 63 libraries + isa-app = ~2MB (production gzipped)
• Tree-shaking removes unused code
• Lazy-loaded routes reduce initial load

---

9. Development Workflow

Adding a New Feature

1. Create feature component
   → Depends on shared components
   
2. Create shared component (if needed)
   → Depends on UI & core libraries
   
3. Update data-access if needed
   → Depends on generated APIs & common
   
4. Import via path aliases
   import { NewFeature } from '@isa/domain/feature/new-feature'
   
5. Verify no circular deps
   npx nx affected:lint

Dependency Investigation

# Show all dependencies of a library
npx nx show project oms-feature-return-search --web false

# Visualize dependency graph
npx nx graph --filter=oms-data-access

# Check for circular dependencies
npx nx lint

# View detailed dependency tree
npx nx show project oms-data-access --web false

---

10. Performance Considerations

Lazy Loading

• Each feature module can be lazy-loaded via routing
• Reduces initial bundle size
• Loads on demand

Tree Shaking

• Unused exports automatically removed
• All libraries use ES6 modules
• Named exports encouraged

Code Splitting

• Generated APIs included only when imported
• UI components tree-shakeable
• Shared components bundled separately

Module Boundaries

isa-app (main bundle)
├── core/ (always loaded)
├── routing (root)
└── route bundles (lazy)
    ├── oms/ (on route navigation)
    ├── remission/ (on route navigation)
    └── checkout/ (on route navigation)

---

11. Breaking Changes Prevention

Strict dependency enforcement prevents:

• ✅ Feature importing data-access from other features
• ✅ UI components importing domain logic
• ✅ Core libraries importing domain logic
• ✅ Circular dependencies
• ✅ Implicit dependencies

Violations caught by:

1. ESLint nx plugin (import-rules)
2. TypeScript compiler (path alias validation)
3. Bundle analysis tools
4. Code review process

---

12. Updating Dependencies

Safe Dependency Diagram Update

1. Update generated API
   → Automatically updates data-access

2. Update core library
   → Cascades to all dependent layers
   
3. Update UI component
   → Only affects features using it
   
4. Update data-access
   → Only affects features in domain

Testing Strategy

• Update → Run affected tests → Deploy
• npx nx affected:test --skip-nx-cache

---

Quick Reference: Which Library to Import

I need a component for...

Use Case	Import From
Button styling	@isa/ui/buttons
Form inputs	@isa/ui/input-controls
Modal dialog	@isa/ui/dialog
Data fetching	@isa/[domain]/data-access
Product display	@isa/shared/product-*
Address display	@isa/shared/address
Logging	@isa/core/logging
Configuration	@isa/core/config
State storage	@isa/core/storage
Tab navigation	@isa/core/tabs
Context preservation	@isa/core/navigation
Printer management	@isa/common/print
EAN validation	@isa/utils/ean-validation
API client	@generated/swagger/[api-name]