# 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:

```typescript
// 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:**
```bash
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

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