ISA-Frontend/CLAUDE.md

CLAUDE.md

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

This is a sophisticated Angular 20.1.2 monorepo managed by Nx 21.3.2. The main application is isa-app, a comprehensive inventory and returns management system for retail/e-commerce operations. The system handles complex workflows including order management (OMS), returns processing (remission), customer relationship management (CRM), product cataloging, and checkout/reward systems.

Architecture

Monorepo Structure

• apps/isa-app: Main Angular application
• libs/: Reusable libraries organized by domain and type
  • core/: Core utilities (config, logging, storage, tabs, navigation)
  • common/: Shared utilities (data-access, decorators, print)
  • ui/: UI component libraries (buttons, dialogs, inputs, etc.)
  • shared/: Shared domain components (filter, scanner, product components)
  • oms/: Order Management System features and utilities
  • remission/: Remission/returns management features
  • catalogue/: Product catalogue functionality
  • utils/: General utilities (validation, scroll position, parsing)
  • icons/: Icon library
• generated/swagger/: Auto-generated API client code from OpenAPI specs

Key Architectural Patterns

• Domain-Driven Design: Clear domain boundaries with dedicated modules (OMS, remission, CRM, catalogue, checkout)
• Layered Architecture: Strict dependency hierarchy (Feature → Shared/UI → Data Access → Infrastructure)
• 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: 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-*)
• Modern State Management: NgRx Signals with entities, session persistence, and reactive patterns

Common Development Commands

Essential Commands (Project-Specific)

# 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

# Build for production
npm run build-prod

# Regenerate all API clients from Swagger/OpenAPI specs
npm run generate:swagger

# Regenerate library reference documentation
npm run docs:generate

# Format code with Prettier
npm run prettier

# Format only staged files (pre-commit hook)
npm run pretty-quick

# Run CI tests with coverage
npm run ci

Standard Nx Commands

For complete command reference, see Nx Documentation.

Common patterns:

# 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 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: 31 libraries (legacy/existing code)
• Vitest: 10 libraries (new standard)
• No test executor: 20 libraries (mostly feature/shared components)

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

Key Requirements

• Test files must end with .spec.ts
• 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.

References:

• Jest Documentation
• Vitest Documentation
• Angular Testing Guide
• Spectator

State Management

• NgRx Signals: Primary state management with modern functional approach using signalStore()
• Entity Management: Uses withEntities() for normalized data storage
• Session Persistence: State persistence with withStorage() using SessionStorageProvider
• Reactive Methods: rxMethod() with takeUntilKeydownEscape() for user-cancellable operations
• Custom RxJS Operators: Specialized operators like takeUntilAborted(), takeUntilKeydown()
• Error Handling: tapResponse() for handling success/error states in stores
• Lifecycle Hooks: withHooks() for cleanup and initialization (e.g., orphaned entity cleanup)
• Navigation State: Use @isa/core/navigation for temporary navigation context (return URLs, wizard state) instead of query parameters

Styling and Design System

• Framework: Tailwind CSS 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

Responsive Design with Breakpoint Service

Use @isa/ui/layout for reactive breakpoint detection instead of CSS-only solutions:

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:

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

• 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

Library Organization

• Naming Pattern: [domain]-[layer]-[feature] (e.g., oms-feature-return-search, ui-buttons)
• Path Aliases: @isa/[domain]/[layer]/[feature] (e.g., @isa/oms/data-access, @isa/ui/buttons)
• Project Names: Found in each library's project.json file, following consistent naming

Component Architecture

• Standalone Components: All new components must be standalone with explicit imports
• Component Prefixes: Domain-specific prefixes for clear identification
  • OMS features: oms-feature-* (e.g., oms-feature-return-search-main)
  • Remission features: remi-*
  • UI components: ui-*
  • Core utilities: core-*
• Signal-based Inputs: Use Angular signals (input(), computed()) for reactive properties
• Host Binding: Dynamic CSS classes via Angular host properties

Dependency Rules

• Unidirectional Dependencies: Feature → Shared/UI → Data Access → Infrastructure
• Import Boundaries: Use path aliases, avoid relative imports across domain boundaries
• Generated API Imports: Import from @generated/swagger/[api-name] for API clients

Code Quality

• Modern Angular Patterns: Prefer inject() over constructor injection
• Type Safety: Use Zod schemas for runtime validation alongside TypeScript
• Error Handling: Custom error classes with specific error codes
• E2E Testing: Always include data-what and data-which attributes in templates

Development Workflow and Best Practices

Project Conventions

• Default Branch: develop (not main) - Always create PRs against develop
• Commit Style: Conventional commits 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-*)

Code Quality Tools

• Linting: ESLint with Nx dependency checks
• Formatting: Prettier with Husky + lint-staged pre-commit hooks
• Type Safety: TypeScript strict mode + Zod validation
• Bundle Size: Monitor carefully (2MB warning, 5MB error for main bundle)

Nx Workflow Tips

• Use npx nx graph to visualize dependencies
• Use npx nx affected:test for CI/CD optimization
• Reference: Nx Documentation

Development Notes and Guidelines

Getting Started

• Application Startup: Only isa-app can be started - it's the main application entry point
• SSL Development: The development server runs with SSL by default (npm start), which is crucial for production-like authentication flows
• Node Requirements: Ensure Node.js ≥22.0.0 and npm ≥10.0.0 before starting development
• First-Time Setup: After cloning, run npm install then npm start to verify everything works

Essential Documentation References

• Testing Guidelines: Review docs/guidelines/testing.md before writing any tests - it covers the Jest→Vitest migration, Spectator→Angular Testing Utilities transition, and E2E attribute requirements
• 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 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:
  • New libraries: Use Vitest + Angular Testing Utilities
  • Existing libraries: Continue with Jest + Spectator until migrated
• Path Aliases: Always use @isa/[domain]/[layer]/[feature] - avoid relative imports across domain boundaries

Library Reference Guide

The monorepo contains 61 libraries organized across 12 domains. For quick lookup of any library's purpose and location, see docs/library-reference.md.

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)

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
• Data Services: Wrap generated API clients in domain-specific data-access services with proper error handling and Zod validation
• State Management: Use NgRx Signals with signalStore(), entity management, and session persistence for complex state

Performance and Quality Considerations

• Bundle Monitoring: Watch bundle sizes (2MB warning, 5MB error for main bundle)
• Testing Cache: Always use --skip-nx-cache flag when running tests to ensure reliable results
• Code Quality: Pre-commit hooks enforce Prettier formatting and ESLint rules automatically
• Memory Management: Clean up subscriptions and use OnPush change detection for optimal performance

Common Troubleshooting

• Build Issues: Check Node version and run npm install if encountering module resolution errors
• Test Failures: Use --skip-nx-cache flag and ensure test isolation (no shared state between tests)
• Nx Cache Issues: If you see existing outputs match the cache, left as is during build or testing:
  • Option 1: Run npx nx reset to clear the Nx cache completely
  • Option 2: Use --skip-nx-cache flag to bypass Nx cache for a specific command (e.g., npx nx test <project> --skip-nx-cache)
  • When to use: Always use --skip-nx-cache when you need guaranteed fresh builds or test results
• SSL Certificates: Development server uses SSL - accept certificate warnings in browser for localhost
• Import Errors: Verify path aliases in tsconfig.base.json and use absolute imports for cross-library dependencies

Domain-Specific Conventions

• Component Prefixes: Use oms-feature-* for OMS, remi-* for remission, ui-* for shared components
• Git Workflow: Default branch is develop (not main), use conventional commits without co-author tags
• 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