ISA-Frontend/docs/architecture-analysis.md

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
2. Dependency Architecture
3. Technology Stack
4. Domain Boundaries
5. Architecture Patterns
6. 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:

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

{
  "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:

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

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:

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

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:

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:

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)

// 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

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

Testing

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

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

API Generation

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

Documentation

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