mirror of
https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend
synced 2025-12-28 22:42:11 +01:00
fd8e0194ac
- Rename logging-helper to logging for consistency - Remove git-commit-helper (superseded by /commit command) - Add git-workflow skill for Git Flow operations Co-Authored-By: Claude <noreply@anthropic.com>
1121 lines
50 KiB
Markdown
1121 lines
50 KiB
Markdown
# 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
|
|
```
|
|
|