# ISA-Frontend Monorepo: Comprehensive Architectural Analysis

**Document Version:** 1.0  
**Last Updated:** 2025-10-29  
**Monorepo Size:** 63 total libraries + 1 main application  
**Angular Version:** 20.3.6  
**Nx Version:** 21.3.2  
**Node.js:** >= 22.12.0, < 23.0.0  
**npm:** >= 11.6.0, < 11.7.0  

---

## Table of Contents

1. [Project Structure Analysis](#project-structure-analysis)
2. [Dependency Architecture](#dependency-architecture)
3. [Technology Stack](#technology-stack)
4. [Domain Boundaries](#domain-boundaries)
5. [Architecture Patterns](#architecture-patterns)
6. [C4 Model Components](#c4-model-components)

---

## Project Structure Analysis

### Overall Organization

The ISA-Frontend is a sophisticated Angular monorepo employing **Domain-Driven Design (DDD)** principles with a strict layered architecture. The project uses Nx workspaces for efficient dependency management and build orchestration.

```
ISA-Frontend/
├── apps/
│   └── isa-app/              # Main Angular application (only runnable app)
│       └── src/
│           ├── app/          # Application bootstrap and root routing
│           ├── domain/       # Domain-specific feature implementations
│           ├── page/         # Page-level components
│           ├── modal/        # Modal dialogs
│           ├── adapter/      # External service adapters
│           ├── core/         # App-specific core services
│           ├── shared/       # App-specific shared utilities
│           ├── ui/           # App-specific UI components
│           ├── utils/        # App-specific utilities
│           ├── config/       # Configuration files
│           ├── environments/ # Environment-specific configs
│           └── assets/       # Static assets
│
├── libs/                     # 63 domain-driven libraries
│   ├── core/                # Core infrastructure (5 libs)
│   ├── common/              # Common utilities (3 libs)
│   ├── ui/                  # UI component system (17 libs)
│   ├── shared/              # Shared domain components (7 libs)
│   ├── availability/        # Availability domain (1 lib)
│   ├── catalogue/           # Catalogue domain (1 lib)
│   ├── checkout/            # Checkout domain (6 libs)
│   ├── crm/                 # CRM domain (1 lib)
│   ├── oms/                 # Order Management domain (9 libs)
│   ├── remission/           # Remission domain (8 libs)
│   ├── icons/               # Icon library (1 lib)
│   ├── utils/               # General utilities (3 libs)
│   └── [domain]/
│       ├── data-access/     # State & API integration
│       ├── feature/         # Feature components
│       ├── shared/          # Domain-specific shared
│       └── utils/           # Domain-specific utilities
│
├── generated/swagger/       # Auto-generated API clients (10 APIs)
│   ├── availability-api/
│   ├── cat-search-api/
│   ├── checkout-api/
│   ├── crm-api/
│   ├── eis-api/
│   ├── inventory-api/
│   ├── isa-api/
│   ├── oms-api/
│   ├── print-api/
│   └── wws-api/
│
├── tools/                   # Build scripts and utilities
├── docs/                    # Documentation
└── config files             # Nx, TypeScript, Prettier configs
```

### Library Count by Domain

| Domain | Count | Libraries |
|--------|-------|-----------|
| **UI Components** | 17 | buttons, carousel, datepicker, dialog, empty-state, expandable, input-controls, item-rows, label, layout, menu, progress-bar, search-bar, skeleton-loader, toolbar, tooltip, bullet-list |
| **OMS (Orders)** | 9 | data-access, feature (return-details, return-process, return-review, return-search, return-summary), shared (product-info, task-list), utils (translation) |
| **Remission (Returns)** | 8 | data-access, feature (remission-list, remission-return-receipt-details, remission-return-receipt-list), shared (product, remission-start-dialog, return-receipt-actions, search-item-to-remit-dialog) |
| **Checkout** | 6 | data-access, feature (reward-catalog, reward-order-confirmation, reward-shopping-cart), shared (product-info, reward-selection-dialog) |
| **Core Infrastructure** | 5 | config, logging, navigation, storage, tabs |
| **Shared Components** | 7 | address, filter, product-format, product-image, product-router-link, quantity-control, scanner |
| **Common Utilities** | 3 | data-access, decorators, print |
| **Utility Libraries** | 3 | ean-validation, scroll-position, z-safe-parse |
| **Specialized Domains** | 4 | availability (1), catalogue (1), crm (1), icons (1) |
| **Generated APIs** | 10 | Auto-generated from Swagger/OpenAPI specs |
| **TOTAL** | **63** | + 1 main application (isa-app) |

---

## Dependency Architecture

### Layer Model

The architecture enforces strict unidirectional dependencies following a layered approach:

```
┌─────────────────────────────────────────────┐
│           Feature Layer (Pages)             │
│    [oms-feature-return-search, etc.]        │
└────────────────┬────────────────────────────┘
                 │ depends on
┌────────────────▼────────────────────────────┐
│      Shared/UI Component Layer              │
│   [oms-shared-product-info, etc.]           │
│   [ui-buttons, ui-dialog, etc.]             │
└────────────────┬────────────────────────────┘
                 │ depends on
┌────────────────▼────────────────────────────┐
│     Data Access & State Layer               │
│   [oms-data-access, checkout-data-access]   │
│         (NgRx Signals Stores)               │
└────────────────┬────────────────────────────┘
                 │ depends on
┌────────────────▼────────────────────────────┐
│    Infrastructure/Common Layer              │
│  [generated-swagger, common-data-access]    │
│  [core-logging, core-config, core-storage]  │
└─────────────────────────────────────────────┘
```

### Import Boundaries

All imports use **path aliases** via TypeScript `tsconfig.base.json`:

```typescript
// Correct (cross-domain)
import { OrderService } from '@isa/oms/data-access';
import { CheckoutService } from '@isa/checkout/data-access';
import { UiButton } from '@isa/ui/buttons';

// Correct (within domain)
import { OrderState } from '../data-access/order.store';

// INCORRECT (relative imports across domains)
// ❌ import { OrderService } from '../../../oms/data-access';
```

### Path Alias Mapping

All 63 libraries are mapped via path aliases:

```json
{
  "paths": {
    "@isa/[domain]/[layer]/[feature]": ["libs/[domain]/[layer]/[feature]/src/index.ts"],
    "@generated/swagger/[api-name]": ["generated/swagger/[api-name]/src/index.ts"]
  }
}
```

### Dependency Graph Overview

**Main Application (isa-app) Dependencies:**
- All 9 OMS libraries
- All 8 Remission libraries
- All 6 Checkout libraries
- Specialized domains: Availability, Catalogue, CRM
- All 17 UI component libraries
- All 7 Shared component libraries
- Core infrastructure: 5 libraries
- Common utilities: 3 libraries
- Generated Swagger APIs: 10 clients
- Utility libraries: 3 libraries

**Key Observations:**
- No circular dependencies (strict acyclic graph)
- Feature libraries depend on shared/UI components
- Shared/UI libraries depend on data-access or core only
- Data-access libraries may depend on generated Swagger APIs and common utilities
- Core libraries have minimal dependencies (infrastructure only)

---

## Technology Stack

### Angular & Build Tools

| Component | Version | Purpose |
|-----------|---------|---------|
| **Angular** | 20.3.6 | Core framework with signals, standalone components |
| **Angular CDK** | 20.2.9 | Component primitives (overlays, focus, platform) |
| **TypeScript** | 5.8.3 | Type safety and modern language features |
| **Nx** | 21.3.2 | Monorepo management and build orchestration |
| **Vite** | 6.3.5 | Fast build tool (for testing) |
| **esbuild** | (via Nx) | Fast JavaScript bundler |

### State Management

| Library | Version | Usage |
|---------|---------|-------|
| **NgRx Signals** | 20.0.0 | Primary state management with signal stores |
| **NgRx Entity** | 20.0.0 | Normalized entity state management |
| **NgRx Effects** | 20.0.0 | Side effects handling |
| **NgRx Store DevTools** | 20.0.0 | Redux DevTools integration |

**State Management Pattern:**
- **signalStore()**: Modern functional signal-based stores
- **withEntities()**: Normalized data with entity adapters
- **withStorage()**: SessionStorage/IDB persistence
- **rxMethod()**: Reactive methods with cancellation support
- **withHooks()**: Lifecycle management and cleanup

### Testing Frameworks

| Framework | Status | Count | Usage |
|-----------|--------|-------|-------|
| **Jest** | Legacy | 40 libs (65.6%) | Older libraries (being phased out) |
| **Vitest** | Standard | 21 libs (34.4%) | New libraries (migration target) |
| **Spectator** | Jest only | - | Advanced mocking for Jest |
| **ng-mocks** | Both | - | Angular-specific mocking utilities |
| **Angular Testing Utilities** | Vitest | - | TestBed, ComponentFixture |

**Testing Strategy:**
- New libraries: Vitest + Angular Testing Utilities
- Legacy libraries: Jest + Spectator
- Migration: Ongoing from Jest to Vitest

### HTTP & API Integration

| Library | Version | Purpose |
|---------|---------|---------|
| **HttpClient** | 20.3.6 | Angular HTTP client |
| **ng-swagger-gen** | 2.3.1 | OpenAPI/Swagger code generation |
| **Zod** | 3.24.2 | Runtime schema validation |

**Generated API Clients (10 total):**
1. `availability-api` - Product availability
2. `cat-search-api` - Catalogue search
3. `checkout-api` - Shopping cart & orders
4. `crm-api` - Customer management
5. `eis-api` - Enterprise Info System
6. `inventory-api` - Inventory management
7. `isa-api` - Main ISA API
8. `oms-api` - Order Management System
9. `print-api` - Print services
10. `wws-api` - Warehouse services

### Form Handling & Input

| Library | Version | Purpose |
|---------|---------|---------|
| **@angular/forms** | 20.3.6 | Reactive and template-driven forms |
| **Angular CDK** | 20.2.9 | Form primitives and accessibility |

### UI & Styling

| Library | Version | Purpose |
|---------|---------|---------|
| **Tailwind CSS** | 3.4.14 | Utility-first CSS framework |
| **ISA Custom Plugins** | - | 7 custom Tailwind plugins (button, typography, menu, label, input, section, select-bullet) |
| **@angular/animations** | 20.3.6 | Animation framework |

### Additional Libraries

| Library | Version | Purpose |
|---------|---------|---------|
| **date-fns** | 4.1.0 | Modern date manipulation |
| **moment** | 2.30.1 | Legacy date library (being replaced by date-fns) |
| **lodash** | 4.17.21 | Utility functions |
| **uuid** | 8.3.2 | UUID generation |
| **RxJS** | 7.8.2 | Reactive programming |
| **@microsoft/signalr** | 8.0.7 | Real-time communication (SignalR) |
| **angular-oauth2-oidc** | 20.0.2 | OAuth2/OIDC authentication |
| **ng2-pdf-viewer** | 10.4.0 | PDF viewing |
| **scandit-web-datacapture** | 6.28.1 | Barcode scanning |
| **ngx-matomo-client** | 8.0.0 | Analytics (Matomo) |

---

## Domain Boundaries

### Domain 1: Order Management System (OMS)

**Purpose:** Handle product returns, receipt management, and return workflow processing

**Libraries (9):**
- `@isa/oms/data-access` - State management for returns/receipts
- `@isa/oms/feature/return-search` - Receipt search & filtering
- `@isa/oms/feature/return-details` - Receipt detail view & item selection
- `@isa/oms/feature/return-process` - Return workflow with questions
- `@isa/oms/feature/return-summary` - Return confirmation & printing
- `@isa/oms/feature/return-review` - Return completion review
- `@isa/oms/shared/product-info` - Product display components
- `@isa/oms/shared/task-list` - Receipt task management
- `@isa/oms/utils/translation` - Receipt type translations

**Key Workflows:**
1. Search for receipts by order ID, EAN, or date range
2. Select items from receipt for return
3. Configure return quantities and categories
4. Answer dynamic return process questions
5. Review and confirm return
6. Print return receipt

**API Dependencies:**
- `oms-api` - Main OMS API
- `isa-api` - General ISA API
- `print-api` - Receipt printing

**State Management:**
- NgRx Signal Store with entity normalization
- Session persistence for in-progress returns

---

### Domain 2: Remission (Returns Management)

**Purpose:** Manage warehouse remission processes (mandatory and department returns)

**Libraries (8):**
- `@isa/remission/data-access` - Remission state and API
- `@isa/remission/feature/remission-list` - Main remission list view
- `@isa/remission/feature/remission-return-receipt-list` - Return receipts view
- `@isa/remission/feature/remission-return-receipt-details` - Receipt details
- `@isa/remission/shared/product` - Product components
- `@isa/remission/shared/remission-start-dialog` - Start remission workflow
- `@isa/remission/shared/return-receipt-actions` - Receipt action buttons
- `@isa/remission/shared/search-item-to-remit-dialog` - Item search dialog

**Key Workflows:**
1. View mandatory (Pflicht) vs department (Abteilung) remissions
2. Create return receipts ("Warenbegleitschein")
3. Assign package numbers
4. Search and add items to remission
5. Complete remission items
6. Delete/continue remission

**API Dependencies:**
- Remission-specific APIs via ISA backend

---

### Domain 3: Checkout & Rewards

**Purpose:** Shopping cart, order placement, and loyalty rewards redemption

**Libraries (6):**
- `@isa/checkout/data-access` - Cart and checkout state
- `@isa/checkout/feature/reward-catalog` - Reward item browsing
- `@isa/checkout/feature/reward-shopping-cart` - Cart with rewards
- `@isa/checkout/feature/reward-order-confirmation` - Order confirmation
- `@isa/checkout/shared/product-info` - Product display
- `@isa/checkout/shared/reward-selection-dialog` - Reward selection UI

**Key Workflows:**
1. Add items to shopping cart
2. View cart items and totals
3. Redeem loyalty points for rewards
4. Browse available rewards
5. Place order with rewards
6. View order confirmation

**API Dependencies:**
- `checkout-api` - Cart and order APIs
- `crm-api` - Customer and bonus card info

**State Management:**
- NgRx Signal Store for cart/checkout state
- Reward selection dialog state

---

### Domain 4: Catalogue

**Purpose:** Product search and catalogue management

**Libraries (1):**
- `@isa/catalogue/data-access` - Catalogue search and filtering

**Key Capabilities:**
- Product search by EAN, title, author
- Loyalty program integration
- Format and edition handling
- Stock availability by location

**API Dependencies:**
- `cat-search-api` - Catalogue search
- `availability-api` - Stock availability

---

### Domain 5: Availability

**Purpose:** Product stock availability across retail locations

**Libraries (1):**
- `@isa/availability/data-access` - Availability queries

**Key Capabilities:**
- Check stock by location
- Support multiple order types
- Delivery method validation

**API Dependencies:**
- `availability-api` - Availability service

---

### Domain 6: CRM (Customer Relationship Management)

**Purpose:** Customer data, addresses, and bonus card management

**Libraries (1):**
- `@isa/crm/data-access` - Customer, address, and bonus card state

**Key Capabilities:**
- Customer lookup and management
- Shipping address management
- Payer information
- Bonus card (Prämienkarte) status and points

**API Dependencies:**
- `crm-api` - Customer management

---

### Shared Component Domains

#### UI Component Library (17 libraries)

Universal design system components used across all domains:

| Component | Purpose |
|-----------|---------|
| `ui-buttons` | Button variants (primary, secondary, ghost, etc.) |
| `ui-input-controls` | Form inputs, checkboxes, radio buttons |
| `ui-dialog` | Modal dialogs and alert boxes |
| `ui-datepicker` | Date range picker |
| `ui-layout` | Responsive layout utilities and breakpoint service |
| `ui-menu` | Dropdown menus |
| `ui-toolbar` | Top bar container |
| `ui-search-bar` | Search input with autocomplete |
| `ui-expandable` | Expandable/collapsible sections |
| `ui-empty-state` | Empty state messages |
| `ui-skeleton-loader` | Loading placeholders |
| `ui-carousel` | Horizontal scroll container |
| `ui-item-rows` | Data row display |
| `ui-progress-bar` | Progress indication |
| `ui-tooltip` | Tooltip overlays |
| `ui-label` | Tag/label components |
| `ui-bullet-list` | Bullet point lists |

**Design System Features:**
- Tailwind CSS + 7 custom plugins
- Custom breakpoints: Tablet, Desktop, DesktopL, DesktopXL
- ISA brand color palette (isa-accent-*, isa-text-*)
- Typography system (14 custom utilities)
- Consistent spacing and sizing

#### Shared Components (7 libraries)

Domain-agnostic components for product display and interaction:

| Component | Purpose |
|-----------|---------|
| `shared-address` | Address display (multi-line, inline) |
| `shared-filter` | Filter and search UI |
| `shared-product-image` | Product image with CDN support |
| `shared-product-format` | Format display (hardcover, audiobook, etc.) |
| `shared-product-router-link` | Product navigation links |
| `shared-quantity-control` | Quantity selector |
| `shared-scanner` | Barcode scanner interface |

---

### Core Infrastructure Libraries (5)

#### `@isa/core/config`
- Type-safe configuration management
- Runtime validation
- Nested object access

#### `@isa/core/logging`
- Structured logging with log levels
- Multiple output sinks (console, remote)
- Hierarchical context support
- Performance optimized

#### `@isa/core/navigation`
- Context preservation for multi-step flows
- Tab-scoped temporary state storage
- Return URL management
- Wizard state preservation

#### `@isa/core/storage`
- Type-safe storage abstraction
- NgRx Signals integration
- Multiple backends: localStorage, sessionStorage, IndexedDB
- Server-side user state sync

#### `@isa/core/tabs`
- Browser-like tab management
- Multi-tab navigation
- History tracking
- Intelligent persistence

---

### Common Utilities (3)

#### `@isa/common/data-access`
- Core data fetching patterns
- RxJS operator library
- Error handling and response models
- Request batching infrastructure

#### `@isa/common/decorators`
- Method validation decorators
- Caching and debouncing
- Rate limiting
- Enhanced logging decorators

#### `@isa/common/print`
- Printer discovery and selection
- Print queue management
- Label and office printer support

---

### Utility Libraries (3)

| Utility | Purpose |
|---------|---------|
| `@isa/utils/ean-validation` | EAN barcode validation with reactive forms |
| `@isa/utils/scroll-position` | Scroll position preservation |
| `@isa/utils/z-safe-parse` | Safe Zod parsing with fallbacks |

---

## Architecture Patterns

### 1. Feature-Based Organization

Each domain follows a **feature-based** organization:

```
libs/[domain]/
├── data-access/      # State store + API services
├── feature/          # Feature components (pages/views)
│   ├── feature-1/
│   ├── feature-2/
│   └── ...
├── shared/           # Domain-specific reusable components
└── utils/            # Domain-specific utilities
```

**Benefits:**
- Clear domain boundaries
- Easy to scale and maintain
- Explicit dependencies
- Parallel team development

### 2. Standalone Components

All new components use Angular's **standalone** architecture:

```typescript
@Component({
  selector: 'oms-return-details',
  standalone: true,
  imports: [CommonModule, OmsSharedModule, UiButtonsModule],
  template: `...`,
})
export class OmsReturnDetailsComponent {}
```

**Advantages:**
- Explicit dependencies in imports
- Tree-shakeable
- Easier to test
- No NgModule boilerplate

### 3. Signal-Based State Management

Uses modern **NgRx Signals** with functional composition:

```typescript
export const orderStore = signalStore(
  withState({ orders: [] as Order[] }),
  withEntities({ entity: type<Order>() }),
  withMethods((store) => ({
    loadOrders: rxMethod<void>(
      pipe(
        switchMap(() => api.getOrders()),
        tapResponse(
          (orders) => patchState(store, setAllEntities(orders)),
          (error) => handleError(error)
        )
      )
    ),
  })),
  withStorage({ key: 'orders' }) // Session persistence
);
```

**Features:**
- Signals for reactive state
- Entity management for normalized data
- Request cancellation via `rxMethod()`
- Automatic persistence
- Type-safe

### 4. Data Access Layer Pattern

Each domain has a dedicated data-access library:

```typescript
// Service wrapping generated API
export class OmsApiService {
  private api = inject(OmsApi);
  
  getReceipt(id: string): Observable<Receipt> {
    return this.api.getReceipt(id).pipe(
      tapResponse(
        (receipt) => Receipt.parse(receipt), // Zod validation
        (error) => this.handleError(error)
      )
    );
  }
}

// Domain store
export const omsStore = signalStore(
  withEntities({ entity: type<Receipt>() }),
  withMethods((store, api = inject(OmsApiService)) => ({
    load: rxMethod<string>(
      pipe(
        switchMap((id) => api.getReceipt(id)),
        tapResponse(
          (receipt) => patchState(store, addEntity(receipt))
        )
      )
    ),
  }))
);
```

### 5. Responsive Design with Breakpoint Service

Uses **breakpoint service** instead of CSS-only solutions:

```typescript
import { breakpoint, Breakpoint } from '@isa/ui/layout';

@Component({
  template: `
    @if (isDesktop()) {
      <desktop-view />
    } @else {
      <mobile-view />
    }
  `,
})
export class ResponsiveComponent {
  isDesktop = breakpoint([
    Breakpoint.Desktop,
    Breakpoint.DesktopL,
    Breakpoint.DesktopXL
  ]);
}
```

**Available Breakpoints:**
- Tablet: max-width 1279px
- Desktop: 1280px - 1439px
- DesktopL: 1440px - 1919px
- DesktopXL: 1920px+

### 6. Error Handling & Validation

Two-tier approach with TypeScript + Zod:

```typescript
import { z } from 'zod';

// Schema definition
const OrderSchema = z.object({
  id: z.string().uuid(),
  items: z.array(OrderItemSchema),
  total: z.number().positive(),
});

type Order = z.infer<typeof OrderSchema>;

// Usage
function processOrder(data: unknown): Result<Order> {
  return OrderSchema.safeParse(data);
}
```

### 7. Request Cancellation

Built-in cancellation support via custom RxJS operators:

```typescript
export class ReturnSearchComponent {
  private searchTerm$ = new Subject<string>();
  
  search$ = this.searchTerm$.pipe(
    debounceTime(300),
    distinctUntilChanged(),
    takeUntilKeydown('Escape'), // Cancel on ESC
    switchMap((term) => this.api.search(term))
  );
}
```

**Custom Operators:**
- `takeUntilAborted()` - Abort signal support
- `takeUntilKeydown()` - Keyboard event cancellation
- `takeUntilKeydownEscape()` - Escape key shortcut

---

## C4 Model Components

### C4 Level 1: System Context

```
┌─────────────────────────────────────────────────────────────┐
│                     ISA Frontend                            │
│  (Angular 20.3.6 Monorepo - Order/Returns Management)      │
│  - OMS (Order Management)                                   │
│  - Remission (Returns Processing)                           │
│  - Checkout (Shopping Cart & Rewards)                       │
│  - Catalogue (Product Search)                               │
│  - CRM (Customer Management)                                │
└──────────────┬──────────────────────────────────────────────┘
               │
      ┌────────┼────────┐
      │        │        │
      ▼        ▼        ▼
┌──────────┐ ┌──────────┐ ┌──────────────┐
│ Backend  │ │Browser/  │ │Native Mobile │
│ REST API │ │Web App   │ │(WebView)     │
└──────────┘ └──────────┘ └──────────────┘
```

### C4 Level 2: Container Architecture

```
┌─────────────────────────────────────────────────────────┐
│              ISA Frontend Application                    │
│           (Angular 20.3.6 SPA + PWA)                     │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │  Routing & Shell                                   │ │
│  │  - isa-app root                                    │ │
│  │  - Tab navigation (5+ open tabs)                   │ │
│  │  - Auth flow                                       │ │
│  └────────────────────────────────────────────────────┘ │
│                      │                                   │
│  ┌──────────────────▼──────────────────────────────┐   │
│  │  Domain Feature Modules                         │   │
│  │  ┌────────────────────────────────────────────┐ │   │
│  │  │ OMS (Return Management)                    │ │   │
│  │  │ - Search → Details → Process → Review      │ │   │
│  │  └────────────────────────────────────────────┘ │   │
│  │  ┌────────────────────────────────────────────┐ │   │
│  │  │ Remission (Warehouse Returns)              │ │   │
│  │  │ - List → Receipt → Actions                 │ │   │
│  │  └────────────────────────────────────────────┘ │   │
│  │  ┌────────────────────────────────────────────┐ │   │
│  │  │ Checkout (Orders & Rewards)                │ │   │
│  │  │ - Cart → Rewards → Confirmation            │ │   │
│  │  └────────────────────────────────────────────┘ │   │
│  │  ┌────────────────────────────────────────────┐ │   │
│  │  │ Catalogue (Product Search)                 │ │   │
│  │  │ - Search → Browse → Details                │ │   │
│  │  └────────────────────────────────────────────┘ │   │
│  │  ┌────────────────────────────────────────────┐ │   │
│  │  │ CRM (Customer Management)                  │ │   │
│  │  │ - Customer → Address → Bonus Card          │ │   │
│  │  └────────────────────────────────────────────┘ │   │
│  └────────────────────────────────────────────────┘ │
│                      │                               │
│  ┌──────────────────▼──────────────────────────────┐ │
│  │  Shared Component Layer                        │ │
│  │  ┌──────────────────────────────────────────┐  │ │
│  │  │ UI Component Library (17 libs)           │  │ │
│  │  │ Buttons, Forms, Dialogs, etc.            │  │ │
│  │  └──────────────────────────────────────────┘  │ │
│  │  ┌──────────────────────────────────────────┐  │ │
│  │  │ Shared Components (7 libs)               │  │ │
│  │  │ Product Info, Address, Scanner, etc.     │  │ │
│  │  └──────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────┘ │
│                      │                               │
│  ┌──────────────────▼──────────────────────────────┐ │
│  │  Data Access & State Layer                     │ │
│  │  ┌──────────────────────────────────────────┐  │ │
│  │  │ Domain Stores (NgRx Signals)             │  │ │
│  │  │ - Order Store                            │  │ │
│  │  │ - Remission Store                        │  │ │
│  │  │ - Checkout Store                         │  │ │
│  │  │ - Catalogue Store                        │  │ │
│  │  │ - CRM Store                              │  │ │
│  │  └──────────────────────────────────────────┘  │ │
│  │  ┌──────────────────────────────────────────┐  │ │
│  │  │ Data Access Services                     │  │ │
│  │  │ (wrapping generated APIs)                │  │ │
│  │  └──────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────┘ │
│                      │                               │
│  ┌──────────────────▼──────────────────────────────┐ │
│  │  Infrastructure & Core Layer                   │ │
│  │  ┌──────────────────────────────────────────┐  │ │
│  │  │ Core Services (5 libs)                   │  │ │
│  │  │ - Config (runtime settings)              │  │ │
│  │  │ - Logging (structured logging)           │  │ │
│  │  │ - Navigation (context preservation)      │  │ │
│  │  │ - Storage (localStorage/IDB)             │  │ │
│  │  │ - Tabs (multi-tab management)            │  │ │
│  │  └──────────────────────────────────────────┘  │ │
│  │  ┌──────────────────────────────────────────┐  │ │
│  │  │ Common Services (3 libs)                 │  │ │
│  │  │ - Data Access (batching, operators)      │  │ │
│  │  │ - Decorators (caching, validation)       │  │ │
│  │  │ - Print (printer management)             │  │ │
│  │  └──────────────────────────────────────────┘  │ │
│  │  ┌──────────────────────────────────────────┐  │ │
│  │  │ Generated Swagger API Clients (10)       │  │ │
│  │  │ - oms-api, checkout-api, crm-api, etc.   │  │ │
│  │  └──────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
        │
        │ HTTP/WebSocket
        │
        ▼
┌──────────────────────────────────────────────────┐
│        Backend Services (REST + SignalR)         │
├──────────────────────────────────────────────────┤
│ - ISA API (core business logic)                  │
│ - OMS API (order management)                     │
│ - Remission API (returns processing)             │
│ - Checkout API (shopping cart)                   │
│ - CRM API (customer data)                        │
│ - Catalogue API (product search)                 │
│ - Availability API (stock checking)              │
│ - Print API (label printing)                     │
│ - EIS API (enterprise info system)               │
│ - WWS API (warehouse services)                   │
└──────────────────────────────────────────────────┘
        │
        ▼
┌──────────────────────────────────────────────────┐
│         External Services                        │
├──────────────────────────────────────────────────┤
│ - Database (SQL Server)                          │
│ - File Storage (CDN for product images)          │
│ - Print Queue (label/office printers)            │
│ - Barcode Scanner (Scandit SDK)                  │
│ - Analytics (Matomo)                             │
│ - OAuth/OIDC (authentication)                    │
└──────────────────────────────────────────────────┘
```

### C4 Level 3: Component Structure (OMS Domain Example)

```
┌──────────────────────────────────────────────────────────────┐
│            OMS Domain (Order Management System)               │
│                 (9 Libraries)                                 │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Feature Components (Route-Level)                      │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-feature-return-search                        │ │ │
│  │  │ - Search for receipts (EAN, order ID, date)      │ │ │
│  │  │ - Filter and pagination                         │ │ │
│  │  │ - Imports: shared/product-info, ui/buttons       │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-feature-return-details                       │ │ │
│  │  │ - View receipt items                            │ │ │
│  │  │ - Select items for return                       │ │ │
│  │  │ - Configure quantities and categories           │ │ │
│  │  │ - Imports: shared/product-info, ui/*            │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-feature-return-process                       │ │ │
│  │  │ - Dynamic return reason questions               │ │ │
│  │  │ - Validation and backend integration            │ │ │
│  │  │ - Imports: data-access, ui/input-controls       │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-feature-return-summary                       │ │ │
│  │  │ - Review all return details                     │ │ │
│  │  │ - Confirm and submit                           │ │ │
│  │  │ - Trigger receipt printing                     │ │ │
│  │  │ - Imports: data-access, shared/*, ui/*         │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-feature-return-review                        │ │ │
│  │  │ - View completed return confirmation            │ │ │
│  │  │ - Display return receipt                        │ │ │
│  │  │ - Option to reprint                            │ │ │
│  │  │ - Imports: data-access, shared/*               │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────────────────┘ │
│                           │                                  │
│  ┌────────────────────────▼────────────────────────────────┐ │
│  │  Shared Components (Reusable UI)                       │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-shared-product-info                         │ │ │
│  │  │ - Product row display                          │ │ │
│  │  │ - EAN, title, author, format, stock info       │ │ │
│  │  │ - Imports: shared/product-*, ui/item-rows      │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-shared-task-list                            │ │ │
│  │  │ - Display return tasks                         │ │ │
│  │  │ - Mark complete/incomplete                     │ │ │
│  │  │ - Imports: ui/expandable, ui/item-rows         │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────────────────┘ │
│                           │                                  │
│  ┌────────────────────────▼────────────────────────────────┐ │
│  │  Data Access Layer                                      │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-data-access                                 │ │ │
│  │  │                                                 │ │ │
│  │  │ NgRx Signal Stores:                            │ │ │
│  │  │ - receiptStore (list, details, filters)        │ │ │
│  │  │ - returnStore (current return process)         │ │ │
│  │  │ - questionStore (dynamic questions)            │ │ │
│  │  │                                                │ │ │
│  │  │ Services:                                      │ │ │
│  │  │ - OmsReceiptService (API wrapper)             │ │ │
│  │  │ - OmsReturnService (return workflow)          │ │ │
│  │  │ - PrintService (receipt printing)             │ │ │
│  │  │                                                │ │ │
│  │  │ Imports: @generated/swagger/oms-api           │ │ │
│  │  │          @generated/swagger/print-api         │ │ │
│  │  │          @isa/core/logging                    │ │ │
│  │  │          @isa/common/data-access              │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────────────────┘ │
│                           │                                  │
│  ┌────────────────────────▼────────────────────────────────┐ │
│  │  Utilities                                              │ │
│  │  ┌──────────────────────────────────────────────────┐ │ │
│  │  │ oms-utils-translation                           │ │ │
│  │  │ - Receipt type translations (Rechnung, etc.)    │ │ │
│  │  │ - Service and pipe for formatting              │ │ │
│  │  └──────────────────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────────────────┘ │
│                           │                                  │
└──────────────────────────┬───────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ OMS API      │ │ Print API    │ │ ISA API      │
│              │ │              │ │              │
│ - getReceipt │ │ - printLabel │ │ - createReturn
│ - listReceipts
│ - createReturn
└──────────────┘ └──────────────┘ └──────────────┘
```

### C4 Level 4: Code Structure (Single Component)

```typescript
// File: libs/oms/feature/return-search/src/return-search.component.ts

import { Component, OnInit, inject } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ReactiveFormsModule } from '@angular/forms';

// Feature dependencies
import { OmsStore, omsStore } from '@isa/oms/data-access';

// Shared components
import { UiSearchBar } from '@isa/ui/search-bar';
import { UiButton, UiPrimaryButton } from '@isa/ui/buttons';
import { OmsProductInfoComponent } from '@isa/oms/shared/product-info';

// Shared utilities
import { UiEmptyState } from '@isa/ui/empty-state';

@Component({
  selector: 'oms-feature-return-search',
  standalone: true,
  imports: [
    CommonModule,
    ReactiveFormsModule,
    UiSearchBar,
    UiButton,
    UiPrimaryButton,
    OmsProductInfoComponent,
    UiEmptyState,
  ],
  template: `
    <div class="oms-return-search">
      <ui-search-bar 
        (search)="onSearch($event)"
        placeholder="EAN oder Bestellnummer eingeben"
      />
      
      @if (store.receipts(); as receipts) {
        @if (receipts.length > 0) {
          <div class="receipt-list">
            @for (receipt of receipts; track receipt.id) {
              <oms-product-info [receipt]="receipt" />
            }
          </div>
        } @else {
          <ui-empty-state
            title="Keine Belege gefunden"
            description="Bitte versuchen Sie es mit einer anderen Suchanfrage"
          />
        }
      }
    </div>
  `,
})
export class OmsReturnSearchComponent implements OnInit {
  // Inject the domain store (NgRx Signals)
  protected store = inject(omsStore);
  
  private router = inject(Router);

  ngOnInit() {
    // Load receipts on component init
    // Store automatically handles state, persistence, etc.
  }

  onSearch(term: string) {
    this.store.searchReceipts(term);
  }
}
```

---

## Architectural Strengths

1. **Strong Domain Separation**: Clear boundaries between OMS, Remission, Checkout, etc.
2. **Scalable Structure**: 63 libraries organized by domain and layer
3. **Type Safety**: TypeScript + Zod validation across all APIs
4. **Modern Patterns**: Standalone components, signals, NgRx Signals stores
5. **Code Reuse**: 17 UI component libraries + 7 shared component libraries
6. **Testing Strategy**: Vitest + Jest with clear framework separation
7. **Build Performance**: Nx caching and incremental builds
8. **State Management**: Centralized, persistent, typed NgRx Signals stores
9. **Error Handling**: Global HTTP interceptors and consistent error patterns
10. **Responsive Design**: Breakpoint service for proper mobile/desktop support

---

## Architectural Considerations

1. **Migration from Jest to Vitest**: Currently 40 Jest libraries, moving to 21 Vitest
2. **Legacy Code**: Some legacy modules still exist alongside new standalone patterns
3. **Bundle Size**: Monitor carefully (2MB warning, 5MB error limits)
4. **Cache Management**: Nx cache can cause issues - use `--skip-nx-cache` for tests
5. **Authentication**: OAuth2/OIDC required for all API calls
6. **Multi-Tab State**: Tab navigation requires careful state management

---

## Key Files for Reference

- **Architecture Definition**: `/nx.json`, `/tsconfig.base.json`
- **Library Reference**: `/docs/library-reference.md`
- **Testing Guidelines**: `/docs/guidelines/testing.md`
- **App Bootstrap**: `/apps/isa-app/src/app/app.module.ts`
- **Routing**: `/apps/isa-app/src/app/app-routing.module.ts`
- **Configuration**: `/apps/isa-app/src/config/`

---

## Deployment & Build Configuration

### Development
```bash
npm start  # Run with SSL (required for auth flows)
```

### Testing
```bash
npm test                    # All libraries except main app
npm run ci                  # CI with coverage
npx nx test <project> --skip-nx-cache  # Specific project (fresh)
```

### Production Build
```bash
npm run build-prod          # Production bundle
npx nx build isa-app --configuration=production
```

### API Generation
```bash
npm run generate:swagger    # Regenerate all 10 Swagger clients
npm run fix:files:swagger   # Unicode cleanup post-generation
```

### Documentation
```bash
npm run docs:generate       # Update library reference
npm run prettier            # Format code
```

