sxhundred/ISA-Frontend
1
0
Fork 0
mirror of https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend synced 2025-12-28 22:42:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: comprehensive CLAUDE.md overhaul with library reference system

Browse Source 
- Restructure CLAUDE.md with clearer sections and updated metadata
- Add research guidelines emphasizing subagent usage and documentation-first approach
- Create library reference guide covering all 61 libraries across 12 domains
- Add automated library reference generation tool
- Complete test coverage for reward order confirmation feature (6 new spec files)
- Refine product info components and adapters with improved documentation
- Update workflows documentation for checkout service
- Fix ESLint issues: case declarations, unused imports, and unused variables
This commit is contained in:
Lorenz Hilpert
2025-10-22 11:55:04 +02:00
parent a92f72f767
commit 743d6c1ee9
31 changed files with 5654 additions and 3632 deletions
Download Patch File Download Diff File Expand all files Collapse all files

674
CLAUDE.md
View File

@@ -1,6 +1,10 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
> **Last Updated:** 2025-10-22
> **Angular Version:** 20.1.2
> **Nx Version:** 21.3.2
> **Node.js:** ≥22.0.0
> **npm:** ≥10.0.0
## Project Overview
@@ -28,7 +32,7 @@ This is a sophisticated Angular 20.1.2 monorepo managed by Nx 21.3.2. The main a
- **Standalone Components**: All new components use Angular standalone architecture with explicit imports
- **Feature Libraries**: Domain features organized as separate libraries (e.g., `oms-feature-return-search`, `remission-feature-remission-list`)
- **Data Access Layer**: Separate data-access libraries for each domain with NgRx Signals stores
- **Shared UI Components**: 15 dedicated UI component libraries with design system integration
- **Shared UI Components**: 18 dedicated UI component libraries with design system integration
- **Generated API Clients**: 10 auto-generated Swagger/OpenAPI clients with post-processing pipeline
- **Path Aliases**: Comprehensive TypeScript path mapping (`@isa/domain/layer/feature`)
- **Component Prefixes**: Domain-specific prefixes (OMS: `oms-feature-*`, Remission: `remi-*`, UI: `ui-*`)
@@ -36,109 +40,84 @@ This is a sophisticated Angular 20.1.2 monorepo managed by Nx 21.3.2. The main a
## Common Development Commands
### Build Commands
### Essential Commands (Project-Specific)
```bash
# Build the main application (development) - default configuration
# Start development server with SSL (required for authentication flows)
npm start
# Run tests for all libraries (excludes main app)
npm test
# Build for development
npm run build
# Or: npx nx build isa-app --configuration=development
# Build for production
npm run build-prod
# Or: npx nx build isa-app --configuration=production
# Build without using Nx cache (for fresh builds)
npx nx build isa-app --skip-nx-cache
# Serve the application with SSL (development server)
npm start
# Or: npx nx serve isa-app --ssl
```
### Testing Commands
```bash
# Run tests for all libraries except the main app (default command)
npm test
# Or: npx nx run-many -t test --exclude isa-app --skip-nx-cache
# Run tests for a specific library (always use --skip-nx-cache for fresh results)
npx nx run <project-name>:test --skip-nx-cache
# Example: npx nx run oms-data-access:test --skip-nx-cache
# Skip Nx cache entirely (important for ensuring fresh builds/tests)
npx nx run <project-name>:test --skip-nx-cache
# Or combine with skip-cache: npx nx run <project-name>:test --skip-nx-cache --skip-nx-cache
# Run a single test file
npx nx run <project-name>:test --testFile=<path-to-test-file> --skip-nx-cache
# Run tests with coverage
npx nx run <project-name>:test --code-coverage --skip-nx-cache
# Run tests in watch mode
npx nx run <project-name>:test --watch
# Run CI tests with coverage (for CI/CD)
npm run ci
# Or: npx nx run-many -t test --exclude isa-app -c ci
```
### Linting Commands
```bash
# Lint a specific project
npx nx lint <project-name>
# Example: npx nx lint remission-data-access
# Run linting for all projects
npx nx run-many -t lint
```
### Other Useful Commands
```bash
# Generate Swagger API clients (regenerates all API clients)
# Regenerate all API clients from Swagger/OpenAPI specs
npm run generate:swagger
# Or: npx nx run-many -t generate -p tag:generated,swagger
# Start Storybook for UI component development
npm run storybook
# Or: npx nx run isa-app:storybook
# Regenerate library reference documentation
npm run docs:generate
# Format code with Prettier
npm run prettier
# Format staged files only (used in pre-commit hooks)
# Format only staged files (pre-commit hook)
npm run pretty-quick
# List all projects in the workspace
npx nx list
# Run CI tests with coverage
npm run ci
```
# Show project dependencies graph (visual)
### Standard Nx Commands
For complete command reference, see [Nx Documentation](https://nx.dev/reference/commands).
**Common patterns:**
```bash
# Test specific library (always use --skip-nx-cache)
npx nx test <project-name> --skip-nx-cache
# Lint a project
npx nx lint <project-name>
# Show project dependencies
npx nx graph
# Run affected tests (based on git changes)
npx nx affected:test
# Run tests for affected projects (CI/CD)
npx nx affected:test --skip-nx-cache
```
**Important:** Always use `--skip-nx-cache` flag when running tests to ensure fresh results.
## Testing Framework
> **Last Reviewed:** 2025-10-22
> **Status:** Migration in Progress (Jest → Vitest)
### Current Setup (Migration in Progress)
- **Jest**: Used by 40 libraries (76% of codebase) - existing/legacy libraries
- **Vitest**: Used by 13 libraries (24% of codebase) - newer libraries and migrations
- **Testing Utilities Migration**:
- **Angular Testing Utilities** (TestBed, ComponentFixture): Preferred for new tests (25 test files)
- **Spectator**: Legacy testing utility for existing tests (56 test files)
- **ng-mocks**: For advanced mocking scenarios and child component mocking
- **Jest**: 31 libraries (legacy/existing code)
- **Vitest**: 10 libraries (new standard)
- **No test executor**: 20 libraries (mostly feature/shared components)
### Migration Status by Domain
- **Migrated to Vitest**: `crm-data-access`, `checkout-*`, several `ui/*` components, `remission/*` libraries
- **Still on Jest**: Core `oms/*` libraries, main application, most legacy libraries
- **New Libraries**: Should use Vitest + Angular Testing Utilities from the start
### Testing Strategy
- **New libraries**: Use Vitest + Angular Testing Utilities (TestBed, ComponentFixture)
- **Legacy libraries**: Continue with Jest + Spectator until migrated
- **Advanced mocking**: Use ng-mocks for complex scenarios
### Test File Requirements
### Key Requirements
- Test files must end with `.spec.ts`
- Use AAA pattern (Arrange-Act-Assert) consistently across both frameworks
- Include E2E testing attributes (`data-what`, `data-which`, dynamic `data-*` attributes) in HTML templates
- Mock external dependencies and child components using appropriate framework tools
- Verify E2E attributes are correctly applied in component unit tests
- Use AAA pattern (Arrange-Act-Assert)
- **Always include E2E attributes**: `data-what`, `data-which`, and dynamic `data-*` in HTML templates
- Mock external dependencies appropriately for your framework
**For detailed testing guidelines, framework comparison, and migration instructions, see [`docs/guidelines/testing.md`](docs/guidelines/testing.md).**
**References:**
- [Jest Documentation](https://jestjs.io/)
- [Vitest Documentation](https://vitest.dev/)
- [Angular Testing Guide](https://angular.io/guide/testing)
- [Spectator](https://ngneat.github.io/spectator/)
## State Management
- **NgRx Signals**: Primary state management with modern functional approach using `signalStore()`
@@ -151,55 +130,63 @@ npx nx affected:test
- **Navigation State**: Use `@isa/core/navigation` for temporary navigation context (return URLs, wizard state) instead of query parameters
## Styling and Design System
- **Tailwind CSS**: Primary styling framework with extensive ISA-specific customization
- **Custom Breakpoints**: `isa-desktop` (1024px), `isa-desktop-l` (1440px), `isa-desktop-xl` (1920px)
- **Brand Color System**: Comprehensive `isa-*` color palette with semantic naming
- **Design Tokens**: Consistent spacing, typography, shadows, and border-radius values
- **Custom Tailwind Plugins** (7 plugins): `button`, `typography`, `menu`, `label`, `input`, `section`, `select-bullet`
- **SCSS Integration**: Component-scoped SCSS with BEM-like naming conventions
- **CSS Custom Properties**: Extensive use of CSS variables for theming and component variants
- **Typography System**: 14 custom text utilities (`.isa-text-heading-1-bold`, `.isa-text-body-2-regular`)
- **UI Component Libraries**: 15 specialized UI libraries with consistent API patterns
- **Storybook Integration**: Component documentation and development environment
- **Responsive Design & Breakpoints**:
- **Breakpoint Service**: Use `@isa/ui/layout` for reactive breakpoint detection in components
- **Available Breakpoints**:
- `Breakpoint.Tablet`: `(max-width: 1279px)` - Mobile and tablet devices
- `Breakpoint.Desktop`: `(min-width: 1280px) and (max-width: 1439px)` - Standard desktop screens
- `Breakpoint.DekstopL`: `(min-width: 1440px) and (max-width: 1919px)` - Large desktop screens
- `Breakpoint.DekstopXL`: `(min-width: 1920px)` - Extra large desktop screens
- **Usage Pattern**:
```typescript
import { breakpoint, Breakpoint } from '@isa/ui/layout';
- **Framework**: [Tailwind CSS](https://tailwindcss.com/docs) with extensive ISA-specific customization
- **Custom Breakpoints**: `isa-desktop` (1024px), `isa-desktop-l` (1440px), `isa-desktop-xl` (1920px)
- **Brand Color System**: `isa-*` color palette with semantic naming
- **Custom Tailwind Plugins** (7): button, typography, menu, label, input, section, select-bullet
- **Typography System**: 14 custom utilities (`.isa-text-heading-1-bold`, `.isa-text-body-2-regular`, etc.)
- **UI Component Libraries**: 18 specialized libraries with consistent APIs (see Library Reference)
- **Storybook**: Component documentation and development at `npm run storybook`
isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.DekstopXL]);
```
- **Template Integration**: Use with `@if` control flow for conditional rendering based on screen size
- **Note**: Prefer the breakpoint service over CSS-only solutions (hidden/flex classes) for proper server-side rendering and better maintainability
### Responsive Design with Breakpoint Service
Use `@isa/ui/layout` for reactive breakpoint detection instead of CSS-only solutions:
```typescript
import { breakpoint, Breakpoint } from '@isa/ui/layout';
// Detect screen size reactively
isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.DekstopXL]);
```
**Available Breakpoints:**
- `Tablet`: max-width: 1279px (mobile/tablet)
- `Desktop`: 1280px - 1439px (standard desktop)
- `DekstopL`: 1440px - 1919px (large desktop)
- `DekstopXL`: 1920px+ (extra large)
**Template Usage:**
```html
@if (isDesktop) {
<!-- Desktop-specific content -->
}
```
**Why:** Prefer breakpoint service over CSS-only (hidden/flex) for SSR and maintainability.
## API Integration and Data Access
- **Generated Swagger Clients**: 10 auto-generated TypeScript clients from OpenAPI specs in `generated/swagger/`
- **Available APIs**: availability-api, cat-search-api, checkout-api, crm-api, eis-api, inventory-api, isa-api, oms-api, print-api, wws-api
- **Generation Tool**: `ng-swagger-gen` with custom configurations per API
- **Post-processing**: Automatic Unicode character cleanup via `tools/fix-files.js`
- **Data Access Architecture**:
- **Business Logic Services**: Domain-specific services that wrap generated API clients
- **Type Safety**: Full TypeScript integration with Zod schema validation
- **Error Handling**: Global HTTP interceptor with custom error classes and automatic re-authentication
- **Configuration Management**: Dynamic API endpoint configuration through dependency injection
- **Request Cancellation**: Built-in support via AbortSignal and custom operators
- **Service Patterns**:
- **Modern Injection**: Uses `inject()` function with private field pattern
- **Logging Integration**: Comprehensive logging throughout data access layer
- **Consistent API**: Standardized service interfaces across all domains
**Generated Swagger Clients:** 10 auto-generated TypeScript clients in `generated/swagger/`
- Available APIs: availability-api, cat-search-api, checkout-api, crm-api, eis-api, inventory-api, isa-api, oms-api, print-api, wws-api
- Tool: [ng-swagger-gen](https://www.npmjs.com/package/ng-swagger-gen) with custom per-API configuration
- Post-processing: Automatic Unicode cleanup via `tools/fix-files.js`
- Regenerate: `npm run generate:swagger`
**Architecture Pattern:**
- Business logic services wrap generated API clients
- Type safety: TypeScript + [Zod](https://zod.dev/) schema validation
- Error handling: Global HTTP interceptor with automatic re-authentication
- Modern injection: Uses `inject()` function with private field pattern
- Request cancellation: Built-in via AbortSignal and custom RxJS operators (`takeUntilAborted()`, `takeUntilKeydown()`)
**Data Access Libraries:** See Library Reference section for domain-specific implementations (`@isa/[domain]/data-access`).
## Build Configuration
- **Angular 20.1.2**: Latest Angular version
- **TypeScript 5.8.3**: For type safety
- **Node.js >= 22.0.0**: Required Node version (specified in package.json engines)
- **npm >= 10.0.0**: Required npm version (specified in package.json engines)
- **Nx 21.3.2**: Monorepo build system and development tools
- **Vite 6.3.5**: Build tool for faster development and testing (used with Vitest)
- **Framework**: Angular with TypeScript (see `package.json` for current versions)
- **Requirements**:
- Node.js >= 22.0.0 (specified in package.json engines)
- npm >= 10.0.0 (specified in package.json engines)
- **Build System**: Nx monorepo with Vite for testing (Vitest)
- **Development Server**: Serves with SSL by default (required for authentication flows)
## Important Conventions and Patterns
@@ -231,34 +218,24 @@ npx nx affected:test
## Development Workflow and Best Practices
### Essential Commands
- **Development**: `npm start` (serves with SSL enabled by default)
- **Testing**: `npm test` (runs all library tests, skips main app)
- **Building**: `npm run build` (development), `npm run build-prod` (production)
- **Code Generation**: `npm run generate:swagger` (regenerates all API clients)
- **Code Quality**: `npm run prettier` (formats all files), `npm run pretty-quick` (staged files only)
### Project Conventions
- **Default Branch**: `develop` (not main) - Always create PRs against develop
- **Commit Style**: [Conventional commits](https://www.conventionalcommits.org/) without co-author tags
- **Nx Cache**: Always use `--skip-nx-cache` for tests to ensure fresh results
- **Testing**: New libraries use Vitest + Angular Testing Utilities; legacy use Jest + Spectator
- **E2E Attributes**: Always include `data-what`, `data-which`, and dynamic `data-*` in templates
- **Design System**: Use ISA-specific Tailwind utilities (`isa-accent-*`, `isa-text-*`)
### Nx Workflow Optimization
- Always use `npx nx run` pattern for executing specific tasks
- Include `--skip-nx-cache` flag when running tests to ensure fresh results
- Use `--skip-nx-cache` to bypass Nx cache entirely for guaranteed fresh builds/tests (important for reliability)
- Use affected commands for CI/CD optimization: `npx nx affected:test`
- Visualize project dependencies: `npx nx graph`
- The default git branch is `develop` (not `main`)
### Code Quality Tools
- **Linting**: [ESLint](https://eslint.org/) with Nx dependency checks
- **Formatting**: [Prettier](https://prettier.io/) with Husky + lint-staged pre-commit hooks
- **Type Safety**: [TypeScript](https://www.typescriptlang.org/) strict mode + [Zod](https://zod.dev/) validation
- **Bundle Size**: Monitor carefully (2MB warning, 5MB error for main bundle)
### Testing Best Practices
- **New Libraries**: Use Vitest + Angular Testing Utilities
- **Legacy Libraries**: Continue using Jest + Spectator until migrated
- **Migration Priority**: UI components and new domains migrate first
- **E2E Attributes**: Verify `data-what`, `data-which`, and dynamic `data-*` attributes in tests
- **Mock Strategy**: Use appropriate framework tools (Spectator's `mocks` array vs TestBed providers)
### Code Quality Guidelines
- **Linting**: ESLint flat config with Nx dependency checks
- **Formatting**: Prettier with pre-commit hooks via Husky and lint-staged
- **Type Safety**: Zod validation for API boundaries, TypeScript strict mode
- **Bundle Optimization**: Monitor bundle sizes (2MB warning, 5MB error for main bundle)
- **Performance**: Use NgRx Signals for reactive state management with session persistence
### Nx Workflow Tips
- Use `npx nx graph` to visualize dependencies
- Use `npx nx affected:test` for CI/CD optimization
- Reference: [Nx Documentation](https://nx.dev/getting-started/intro)
## Development Notes and Guidelines
@@ -273,9 +250,101 @@ npx nx affected:test
- **Code Review Standards**: Follow the structured review process in `.github/review-instructions.md` with categorized feedback (🚨 Critical, ❗ Minor, ⚠️ Warnings, ✅ Good Practices)
- **E2E Testing Requirements**: Always include `data-what`, `data-which`, and dynamic `data-*` attributes in HTML templates - these are essential for automated testing by QA colleagues
### Researching and Investigating the Codebase
**🚨 CRITICAL: Always Research Before Implementation**
**NEVER assume you know the answer - AI models are never up-to-date:**
- Before working on ANY problem, research the needed information and documentation
- Even if you think you know how something works, verify with current documentation
- Use `docs-researcher` to check library READMEs, `/docs` files, and API documentation
- Use `Explore` to verify how similar features are currently implemented
- Your training data has a cutoff - the actual codebase is the source of truth
**🚨 CRITICAL: Keep Main Context Clean - Always Use Subagents**
**When to use `docs-researcher` subagent:**
- Reading and analyzing library READMEs
- Searching and extracting information from `/docs` directory
- Analyzing library documentation when unclear
- Understanding API documentation and usage patterns
- Any documentation-heavy research task
**When to use `Explore` subagent:**
- Searching for patterns across the codebase
- Finding similar implementations
- Exploring component structures
- Discovering how features are implemented
- Any task requiring multiple file reads/searches
**General Approach:**
1. **ALWAYS research first** - Never assume you know the answer, verify with current documentation
2. **Start with the Library Reference Guide** (see below) for quick library lookup
3. **Use `docs-researcher` for ALL documentation research** - Keeps main context clean
4. **Use `Explore` for codebase exploration** - Prevents context pollution during searches
5. **Use Nx tools for architecture visualization** - `npx nx graph` to understand dependencies
6. **Follow error messages** - TypeScript/runtime errors point to exact locations
**Finding Information by Type:**
| What are you looking for? | Where to search | How |
|---------------------------|-----------------|-----|
| **A specific library's purpose** | Library Reference Guide (below) | Look up by domain/name |
| **How to use a library** | `libs/[domain]/[layer]/[feature]/README.md` | **Use `docs-researcher` subagent** |
| **Project guidelines** | `/docs` directory | **Use `docs-researcher` subagent** |
| **Project dependencies** | `npx nx graph` | Visualize which projects depend on which |
| **Similar existing implementations** | Across codebase | **Use `Explore` subagent** to find patterns |
| **Component structure** | Domain-specific feature folders | **Use `Explore` subagent** for deep dives |
| **State management patterns** | `libs/[domain]/data-access/` | **Use `Explore` subagent** to find stores |
| **API integration examples** | `generated/swagger/` + data-access | **Use `Explore` subagent** to find usage |
| **Styling/Design tokens** | `tailwind.config.js` + `tailwind-plugins/` | **Use `Explore` subagent** for patterns |
| **Error handling patterns** | `libs/common/data-access/` | **Use `Explore` subagent** to find operators |
| **UI components** | `libs/ui/[component]/README.md` | **Use `docs-researcher` or Storybook** |
**Effective Subagent Usage:**
**Using `docs-researcher` subagent (for documentation):**
```
Task: Read and analyze README.md for @isa/[domain]/[layer]/[feature]
Focus on: Purpose, main exports, usage patterns, dependencies, examples
Task: Search /docs for testing guidelines
Focus on: Extract relevant sections about Jest/Vitest migration
Task: Analyze library documentation when API is unclear
Focus on: Clarify usage patterns, parameters, return types
```
**Using `Explore` subagent (for codebase):**
```
Task: Find all implementations of error handling patterns
Thoroughness: "medium" or "very thorough" depending on complexity
Task: Search for similar component structures in remission domain
Thoroughness: "medium"
Task: Discover how NgRx Signals stores are used across data-access libraries
Thoroughness: "very thorough"
```
**Using Nx tools (for architecture):**
```
- Run: npx nx graph --filter=[project-name]
- Look at which projects this one depends on (imports from)
- Look at which projects depend on it (things that import from it)
- This shows you the dependency chain and data flow
```
**Debugging Tips:**
- **TypeScript errors**: Follow the error path - it points to the exact file and line
- **Runtime errors**: Check browser console (F12) and network tab for API issues
- **Test failures**: Use `--skip-nx-cache` to get fresh test output with full error details
- **Module resolution**: Check `tsconfig.base.json` path aliases to understand import resolution
- **State issues**: Use Angular DevTools browser extension to inspect NgRx state
### Library Development Patterns
- **Understanding Internal Libraries**: Before using any internal library from the `libs/` directory, always read its README.md file first to understand its purpose, API, and proper usage patterns
- **Library Documentation**: All libraries have comprehensive README.md documentation. To prevent context pollution, **always use a subagent** (preferably `docs-architect` or `general-purpose`) to retrieve specific information from library documentation rather than reading the entire file directly
- **Understanding Internal Libraries**: Before using any internal library from the `libs/` directory, always read its README.md file using the **`docs-researcher` subagent** to understand its purpose, API, and proper usage patterns
- **Library Documentation**: All libraries have comprehensive README.md documentation. **To keep main context clean, ALWAYS use the `docs-researcher` subagent** to retrieve and analyze library documentation rather than reading files directly
- **New Library Creation**: Use Nx generators with domain-specific naming (`[domain]-[layer]-[feature]`)
- **Standalone Components**: All new components must be standalone with explicit imports - no more NgModules
- **Testing Framework Selection**:
@@ -285,93 +354,13 @@ npx nx affected:test
#### Library Reference Guide
All 62 libraries in the monorepo have comprehensive README.md documentation. Use subagents to retrieve specific information from these READMEs to avoid context pollution.
The monorepo contains **61 libraries** organized across 12 domains. For quick lookup of any library's purpose and location, see **[`docs/library-reference.md`](docs/library-reference.md)**.
**Availability Domain (1 library)**
- `@isa/availability/data-access` - Product availability service supporting 6 order types (InStore, Pickup, Delivery, DIG-Versand, B2B-Versand, Download) with intelligent routing, Zod validation, and business rule enforcement
**Quick Overview by Domain:**
- Availability (1) | Catalogue (1) | Checkout (6) | Common (3) | Core (5) | CRM (1) | Icons (1)
- OMS (9) | Remission (8) | Shared Components (7) | UI Components (16) | Utilities (3)
**Catalogue Domain (1 library)**
- `@isa/catalogue/data-access` - Product search and availability validation service with multi-type search (EAN, Term, Loyalty), download validation, and DIG/B2B delivery availability
**Checkout Domain (6 libraries)**
- `@isa/checkout/data-access` - Shopping cart management and checkout orchestration supporting 6 order types with reward system integration, payment type logic, and CRM data transformation
- `@isa/checkout/feature/reward-order-confirmation` - Order confirmation page for reward/premium orders with address display and item list
- `@isa/checkout/feature/reward-shopping-cart` - Complete reward shopping cart feature with checkout workflow, item management, and order completion orchestration
- `@isa/checkout/feature/reward-catalog` - Reward catalog browsing with customer bonus points, filtering, pagination, and item selection
- `@isa/checkout/shared/product-info` - Product information display components for checkout (redemption info, destination info, stock info)
- `@isa/checkout/shared/reward-selection-dialog` - Product selection dialog for adding items to reward shopping cart
**Common Libraries (3 libraries)**
- `@isa/common/data-access` - Foundational data access utilities including error hierarchy, custom RxJS operators (takeUntilAborted, takeUntilKeydown), batching infrastructure, and Zod integration
- `@isa/common/decorators` - TypeScript decorators for validation (ValidateParams), caching (Cache), debouncing (Debounce), and in-flight request management (InFlight, InFlightWithKey, InFlightWithCache)
- `@isa/common/print` - Platform-aware print service supporting both label and office printers with smart printer selection and reusable print dialog components
**Core Libraries (5 libraries)**
- `@isa/core/config` - Type-safe configuration management with runtime Zod validation, nested object access via dot notation, and environment-specific configuration
- `@isa/core/logging` - Centralized logging service with log levels, contextual information, and Angular integration
- `@isa/core/navigation` - Context preservation service for multi-step navigation flows with automatic tab-scoped storage and cleanup
- `@isa/core/storage` - User storage abstraction with SessionStorage/IndexedDB backends and automatic serialization
- `@isa/core/tabs` - Tab management system with NgRx Signals, persistent storage, intelligent history pruning, and Router integration
**CRM Domain (1 library)**
- `@isa/crm/data-access` - Customer relationship management data access with customer fetching, shipping address management, bonus cards, payer info, and tab-based state management
**Icons (1 library)**
- `@isa/icons` - Icon library with Angular icon components and SVG assets
**OMS Domain (9 libraries)**
- `@isa/oms/data-access` - Order Management System data access with return search, question-based workflows, state management (3 stores), and print integration
- `@isa/oms/feature/return-details` - Receipt details view with item display, customer history, quantity management, and return eligibility validation
- `@isa/oms/feature/return-process` - Dynamic question-based return process with 6 product categories, 5 question types, form validation, and state persistence
- `@isa/oms/feature/return-review` - Final review step for return process with task summary, receipt reprinting, and navigation protection
- `@isa/oms/feature/return-search` - Return search with filtering, pagination, infinite scroll, and automatic redirect to details when single result found
- `@isa/oms/feature/return-summary` - Pre-submission summary of return process with item review and final confirmation before order creation
- `@isa/oms/shared/product-info` - Product display component for OMS workflows with image, navigation, and format icons
- `@isa/oms/shared/task-list` - Task list component with dual appearance modes (main/review), NgRx integration, and tab-based isolation
- `@isa/oms/utils/translation` - Receipt type translation utility with 13 German translations and dependency injection support
**Remission Domain (8 libraries)**
- `@isa/remission/data-access` - Remission/returns management data access supporting Pflichtremission (mandatory) and Abteilungsremission (department overflow) with stock batching, state management, and supplier/branch services
- `@isa/remission/feature/remission-list` - Main remission list with dual types, filtering, search, and resource-based data fetching
- `@isa/remission/feature/remission-return-receipt-details` - Receipt details view with items, metadata, and action integration
- `@isa/remission/feature/remission-return-receipt-list` - List view for all return receipts with sorting, filtering, and parallel resource fetching
- `@isa/remission/shared/product` - Product display components for remission workflows (info, stock info, shelf meta)
- `@isa/remission/shared/remission-start-dialog` - Two-step dialog for receipt creation and package assignment
- `@isa/remission/shared/return-receipt-actions` - Action components for receipt deletion, continuation, and completion
- `@isa/remission/shared/search-item-to-remit-dialog` - Dialog for adding unlisted items to remission with search-to-remit flow
**Shared Component Libraries (7 libraries)**
- `@isa/shared/address` - Address display components (multi-line and inline) with country name resolution and German address special handling
- `@isa/shared/filter` - Advanced filtering system with filter groups, date ranges, search, and scanner integration
- `@isa/shared/product-format` - Product format display with icon and text components supporting 6 format codes (HC, PB, EB, AB, DIG, AUD)
- `@isa/shared/product-image` - Product image directive with CDN integration, configurable dimensions, and lazy loading
- `@isa/shared/product-router-link` - EAN-based product navigation directive with pluggable URL builder pattern
- `@isa/shared/quantity-control` - Accessible quantity selector with dropdown presets, manual input mode, and smart logic
- `@isa/shared/scanner` - Barcode scanner integration with camera and keyboard input support
**UI Component Libraries (17 libraries)**
- `@isa/ui/bullet-list` - Bullet list component with parent-child icon inheritance and signal-based reactivity
- `@isa/ui/buttons` - Five button components (Button, TextButton, IconButton, InfoButton, StatefulButton) with pending states, size/color variants, and ARIA support
- `@isa/ui/datepicker` - Range datepicker with validators, calendar views, and ControlValueAccessor integration
- `@isa/ui/dialog` - Dialog system with 5 preset types (message, confirmation, text-input, number-input, feedback) and injection-based API
- `@isa/ui/empty-state` - Empty state component with 4 appearance variants (general, no-results, no-data, error) and SVG icons
- `@isa/ui/expandable` - Expandable/collapsible container with smooth animations
- `@isa/ui/input-controls` - Form control components (checkbox, dropdown, text-field, chips, checklist, listbox, inline-input) with ControlValueAccessor integration
- `@isa/ui/item-rows` - Item display rows with data components and directive-based composition
- `@isa/ui/label` - Label component with Tag/Notice types and High/Medium/Low priority levels
- `@isa/ui/layout` - Breakpoint service for responsive design with 4 breakpoints (Tablet, Desktop, DesktopL, DesktopXL)
- `@isa/ui/menu` - CDK Menu wrapper components with keyboard navigation and ARIA compliance
- `@isa/ui/progress-bar` - Determinate and indeterminate progress indicators with computed width
- `@isa/ui/search-bar` - Search bar with clear button, Angular Forms integration, and focus management
- `@isa/ui/skeleton-loader` - Loading state component with structural directive and customizable dimensions
- `@isa/ui/toolbar` - Toolbar component with two size variants (small/medium) and content projection
- `@isa/ui/tooltip` - Tooltip directive with positioning and accessibility
- `@isa/ui/bullet-list` - Bullet list component with customizable icons and nested list support
**Utility Libraries (3 libraries)**
- `@isa/utils/ean-validation` - EAN barcode validation with Angular Forms validator, standalone validation function, and comprehensive GS1 prefix reference
- `@isa/utils/scroll-position` - Scroll position restoration service with tab-based storage
- `@isa/utils/z-safe-parse` - Safe Zod parsing utility with automatic fallback and console warnings
**IMPORTANT: Always use the `docs-researcher` subagent** to retrieve and analyze library documentation from `libs/[domain]/[layer]/[feature]/README.md`. This keeps the main context clean and prevents pollution
### API Integration Workflow
- **Swagger Generation**: Run `npm run generate:swagger` to regenerate all 10 API clients when backend changes
@@ -400,214 +389,3 @@ All 62 libraries in the monorepo have comprehensive README.md documentation. Use
- **Design System**: Use ISA-specific Tailwind utilities (`isa-accent-*`, `isa-text-*`) and custom breakpoints (`isa-desktop-*`)
- **Logging**: Use centralized logging service (`@isa/core/logging`) with contextual information for debugging
- **Navigation State**: Use `@isa/core/navigation` for passing temporary state between routes (return URLs, form context) instead of query parameters - keeps URLs clean and state reliable
## Claude Code Workflow Definition
Based on comprehensive analysis of development patterns and available tools/MCP servers, here's the formal workflow for handling requests using the Task tool with specialized subagents:
### Phase 1: Request Analysis and Routing
#### 1.1 Initial Analysis (Always Use Subagents)
**Trigger**: Any user request
**Subagents**: `general-purpose` (for research) + domain specialists as needed
```
1. Parse request intent and complexity level
2. Classify request type:
- Feature Development (new functionality)
- Bug Fix/Maintenance (corrections)
- Code Quality/Refactoring (improvements)
- Testing/QA (validation)
- Architecture/Design (structure)
- Research/Investigation (exploration)
3. Assess information completeness and ambiguity
4. Determine required domains and expertise
```
#### 1.2 Clarification Decision Matrix
```
IF (high ambiguity + high impact) → REQUEST clarification
IF (medium ambiguity + architectural changes) → REQUEST optional clarification
IF (low ambiguity OR simple changes) → PROCEED with documented assumptions
```
### Phase 2: Task Decomposition and Agent Assignment
#### 2.1 Complexity-Based Routing
**Simple Tasks (Single file, isolated change)**:
- Route directly to specialist (`frontend-developer`, `typescript-pro`, etc.)
- Single quality gate at completion
**Moderate Tasks (Multiple related files, limited scope)**:
- Decompose into 2-4 parallel subagent tasks
- Example: `angular-mcp` + `test-automator` + `docs-architect`
**Complex Tasks (Multiple domains, significant scope)**:
- Hierarchical task tree with dependencies
- Example: `general-purpose` (analysis) → `nx-mcp` (structure) → `frontend-developer` + `test-automator` (parallel) → `code-reviewer` (validation)
**Architectural Tasks (System-wide changes)**:
- Multi-phase with user approval gates
- Example: `architect-review` → user approval → `frontend-developer` + `backend-architect` + `database-optimizer` → `performance-engineer` (validation)
#### 2.2 Optimal Agent Combinations
**Feature Development Pattern**:
```
context7 (fetch latest APIs)
→ frontend-developer + test-automator (parallel TDD)
→ ui-ux-designer (if UI changes)
→ code-reviewer (quality validation)
```
**Bug Fix Pattern**:
```
error-detective (analyze issue)
→ debugger (reproduce and fix)
→ test-automator (regression tests)
→ performance-engineer (if performance-related)
```
**Refactoring Pattern**:
```
general-purpose (understand current state)
→ legacy-modernizer (plan modernization)
→ test-automator (safety tests)
→ frontend-developer (implement changes)
→ architect-review (validate architecture)
```
### Phase 3: Execution with Progressive Quality Gates
#### 3.1 Standard Execution Flow
```
1. Each subagent receives atomic task with clear requirements
2. Subagent performs implementation with embedded quality checks
3. Results validated against project standards (E2E attributes, naming conventions)
4. Integration compatibility verified
5. Progress reported to user with next steps
```
#### 3.2 Quality Gates by Task Type
- **Code Changes**: `test-automator` → `code-reviewer` → `performance-engineer`
- **UI Changes**: `ui-visual-validator` → `frontend-security-coder` → `code-reviewer`
- **Architecture Changes**: `architect-review` → user approval → implementation → `performance-engineer`
- **API Changes**: `api-documenter` → `backend-security-coder` → integration tests
### Phase 4: Integration and Validation
#### 4.1 Continuous Validation
```
- Every file change triggers appropriate quality subagent
- Integration points validated by architect-review
- Performance impacts assessed by performance-engineer
- Security changes reviewed by security-auditor
```
#### 4.2 User Communication Strategy
```
- Real-time: Critical decisions and blockers
- Milestone-based: Major phase completions
- Exception-driven: Alternative approaches or issues
- Summary-based: Long-running workflow progress
```
### Specialized Subagent Usage Patterns
#### **Always Use These Subagents Proactively**:
- `general-purpose`: For codebase analysis, research, and complex multi-step tasks
- Available specialist agents based on task requirements (see full list below)
#### **Available MCP Server Integration**:
- **nx-mcp**: `nx_workspace`, `nx_project_details`, `nx_run_generator`, `nx_visualize_graph`, etc.
- **angular-mcp**: `list_projects`, `search_documentation`
- **context7**: `resolve-library-id`, `get-library-docs` for latest package documentation
#### **Project-Relevant Subagent Types**:
**Tier 1 - Essential (Most Frequently Needed)**:
- `frontend-developer`: Angular 20.1.2 feature development, standalone components, domain library implementation
- `typescript-pro`: Advanced TypeScript 5.8.3 patterns, type system optimization, interface design
- `test-automator`: Jest→Vitest migration, Spectator→Angular Testing Utilities, unit testing, E2E attributes
- `ui-ux-designer`: Tailwind CSS design system, UI component libraries, responsive design
**Tier 2 - Important (Regularly Needed)**:
- `code-reviewer`: ESLint compliance, Angular best practices, code quality validation
- `performance-engineer`: Angular optimization, bundle analysis, NgRx performance patterns
- `api-documenter`: Swagger/OpenAPI integration, API client documentation
- `docs-architect`: Technical documentation, architecture guides, CLAUDE.md maintenance
**Tier 3 - Specialized (Domain-Specific)**:
- `architect-review`: Nx monorepo architecture, domain-driven design validation
- `frontend-security-coder`: Angular security patterns, XSS prevention, authentication flows
- `deployment-engineer`: Angular build pipelines, Nx CI/CD, npm script automation
- `debugger`: Error analysis, RxJS debugging, state management troubleshooting
**Cross-Cutting Support**:
- `general-purpose`: Complex analysis, codebase research, multi-domain investigations
- `error-detective`: Production issue investigation, log analysis, performance bottlenecks
### Escalation and Error Handling
#### Immediate Escalation Triggers:
- Subagent cannot access required files or resources
- Conflicting requirements between parallel tasks
- Security vulnerabilities discovered
- Breaking changes with no compatibility path
#### Recovery Hierarchy:
1. Subagent self-resolution (retry with different approach)
2. Alternative subagent assignment (different specialist)
3. Task redecomposition (break down further)
4. User consultation (clarification or decision needed)
### Example Workflow: "Add Dark Mode Feature"
```
1. ANALYSIS PHASE:
Task(general-purpose, "Research Angular/Tailwind dark mode patterns and analyze ISA theme system")
2. PLANNING PHASE:
Task(ui-ux-designer, "Design dark mode integration with ISA color system and Tailwind classes")
Task(frontend-developer, "Plan component modifications and theme service architecture")
3. IMPLEMENTATION PHASE (can run in parallel):
Task(frontend-developer, "Implement Angular theme service and component modifications")
Task(typescript-pro, "Create TypeScript interfaces and type-safe theme system")
Task(test-automator, "Create Jest/Vitest tests with E2E attributes for theme functionality")
4. VALIDATION PHASE:
Task(code-reviewer, "Review Angular patterns, NgRx integration, and code quality")
Task(performance-engineer, "Assess bundle size impact and runtime performance")
5. INTEGRATION PHASE:
Task(test-automator, "Run full Nx test suite and validate E2E attributes")
Task(docs-architect, "Update Storybook documentation and component usage guides")
```
### MCP Server Integration Workflow: "Integrate New Angular Library"
```
1. RESEARCH PHASE:
- Use mcp__context7__resolve-library-id to find the library
- Use mcp__context7__get-library-docs to understand APIs
- Use mcp__angular-mcp__search_documentation for Angular integration patterns
2. PROJECT SETUP:
- Use mcp__nx-mcp__nx_generators to find appropriate generators
- Use mcp__nx-mcp__nx_run_generator to scaffold integration components
- Use mcp__nx-mcp__nx_project_details to understand impact scope
3. IMPLEMENTATION WITH SUBAGENTS:
Task(typescript-pro, "Create TypeScript interfaces for library integration")
Task(frontend-developer, "Implement Angular service wrapping the library")
Task(test-automator, "Create unit and integration tests")
4. VALIDATION:
- Use mcp__nx-mcp__nx_visualize_graph to verify dependency relationships
- Use mcp__nx-mcp__nx_current_running_tasks_details to monitor builds
Task(code-reviewer, "Review integration patterns and code quality")
```
This comprehensive workflow leverages ALL available MCP servers and specialized subagents for maximum efficiency, with each agent handling both analysis AND implementation tasks according to their expertise.