# 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)
```bash
# 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](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 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`](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()`
- **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](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**: 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:

```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 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
- **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](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-*`)

### 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)

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

### 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`](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