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

🔴 CRITICAL: Mandatory Agent Usage

You MUST use these subagents for ALL research tasks:

• docs-researcher: For ALL documentation (packages, libraries, READMEs)
• docs-researcher-advanced: Auto-escalate when docs-researcher fails
• Explore: For ALL code pattern searches and multi-file analysis
• Direct tools (Read/Bash): ONLY for single specific files or commands

Violations of this rule degrade performance and context quality. NO EXCEPTIONS.

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: 17 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: 40 libraries (65.6% - legacy/existing code)
• Vitest: 21 libraries (34.4% - new standard)
• All formal libraries now have test executors configured

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

🔴 MANDATORY: You MUST use subagents for research. Direct file reading/searching is FORBIDDEN except for single specific files.

Required Agent Usage

Task Type	Required Agent	Escalation Path
Package/Library Documentation	docs-researcher	→ docs-researcher-advanced if not found
Internal Library READMEs	docs-researcher	Keep context clean
Code Pattern Search	Explore	Set thoroughness level
Implementation Analysis	Explore	Multiple file analysis
Single Specific File	Read tool directly	No agent needed

Documentation Research System (Two-Tier)

1. ALWAYS start with docs-researcher (Haiku, 30-120s) for any documentation need
2. Auto-escalate to docs-researcher-advanced (Sonnet, 2-7min) when:
   • Documentation not found
   • Conflicting sources
   • Need code inference
   • Complex architectural questions

Enforcement Examples

❌ WRONG: Read libs/ui/buttons/README.md
✅ RIGHT: Task → docs-researcher → "Find documentation for @isa/ui/buttons"

❌ WRONG: Grep for "signalStore" patterns
✅ RIGHT: Task → Explore → "Find all signalStore implementations"

❌ WRONG: WebSearch for Zod documentation
✅ RIGHT: Task → docs-researcher → "Find Zod validation documentation"

Remember: Using subagents is NOT optional - it's mandatory for maintaining context efficiency and search quality.

Common Research Patterns

Information Need	Required Approach
Library documentation	docs-researcher → Check library-reference.md → Escalate if needed
Code patterns/examples	Explore with "medium" or "very thorough"
Architecture understanding	npx nx graph + Explore for implementation
Debugging/errors	Direct tool use (Read specific error file, check console)

Debugging Tips

• TypeScript errors: Follow error path to exact file:line
• Test failures: Use --skip-nx-cache for fresh output
• Module resolution: Check tsconfig.base.json path aliases
• State issues: Use Angular DevTools browser extension

Library Development Patterns

• Library Documentation: Use docs-researcher for ALL library READMEs (mandatory for context management)
• 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 NgModules
• Testing Framework: New = Vitest + Angular Testing Utilities, Legacy = Jest + Spectator
• Path Aliases: Always use @isa/[domain]/[layer]/[feature] - avoid relative imports

Library Reference Guide

The monorepo contains 62 libraries organized across 12 domains. For quick lookup, 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 (17) | Utilities (3)

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