# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an Angular monorepo managed by Nx. The main application is `isa-app`, which appears to be an inventory and returns management system for retail/e-commerce.

## Architecture

### Monorepo Structure
- **apps/isa-app**: Main Angular application
- **libs/**: Reusable libraries organized by domain and type
  - **core/**: Core utilities (config, logging, storage, tabs)
  - **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
- **Standalone Components**: Project uses Angular standalone components
- **Feature Libraries**: Domain features organized as separate libraries (e.g., `oms-feature-return-search`)
- **Data Access Layer**: Separate data-access libraries for each domain (e.g., `oms-data-access`, `remission-data-access`)
- **Shared UI Components**: Reusable UI components in `libs/ui/`
- **Generated API Clients**: Swagger/OpenAPI clients auto-generated in `generated/swagger/`

## Common Development Commands

### Build Commands
```bash
# Build the main application (development)
npx nx build isa-app --configuration=development

# Build for production
npx nx build isa-app --configuration=production

# Serve the application with SSL
npx nx serve isa-app --ssl
```

### Testing Commands
```bash
# Run tests for a specific library (always use --skip-cache)
npx nx run <project-name>:test --skip-cache
# Example: npx nx run remission-data-access:test --skip-cache

# Run tests for all libraries except the main app
npx nx run-many -t test --exclude isa-app --skip-cache

# Run a single test file
npx nx run <project-name>:test --testFile=<path-to-test-file> --skip-cache

# Run tests with coverage
npx nx run <project-name>:test --code-coverage --skip-cache

# Run tests in watch mode
npx nx run <project-name>:test --watch
```

### 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
npm run generate:swagger

# Start Storybook
npx nx run isa-app:storybook

# Format code with Prettier
npm run prettier

# List all projects in the workspace
npx nx list

# Show project dependencies graph
npx nx graph

# Run affected tests (based on git changes)
npx nx affected:test
```

## Testing Framework

### Current Setup
- **Jest**: Primary test runner for existing libraries
- **Vitest**: Being adopted for new libraries (migration in progress)
- **Testing Utilities**: 
  - **Angular Testing Utilities** (TestBed, ComponentFixture): Use for new tests
  - **Spectator**: Legacy testing utility for existing tests
  - **ng-mocks**: For advanced mocking scenarios

### Test File Requirements
- Test files must end with `.spec.ts`
- Use AAA pattern (Arrange-Act-Assert)
- Include E2E testing attributes (`data-what`, `data-which`) in HTML templates
- Mock external dependencies and child components

## State Management
- **NgRx**: Store, Effects, Entity, Component Store, Signals
- **RxJS**: For reactive programming patterns

## Styling
- **Tailwind CSS**: Primary styling framework with custom configuration
- **SCSS**: For component-specific styles
- **Custom Tailwind plugins**: For buttons, inputs, menus, typography

## API Integration
- **Generated Swagger Clients**: Auto-generated TypeScript clients from OpenAPI specs
- **Available APIs**: availability, cat-search, checkout, crm, eis, inventory, isa, oms, print, wws

## Build Configuration
- **Angular 20.1.2**: Latest Angular version
- **TypeScript 5.8.3**: For type safety
- **Node.js >= 22.0.0**: Required Node version
- **npm >= 10.0.0**: Required npm version

## Important Conventions
- **Component Prefix**: Each library has its own prefix (e.g., `remi` for remission, `oms` for OMS)
- **Standalone Components**: All new components should be standalone
- **Path Aliases**: Use TypeScript path aliases defined in `tsconfig.base.json` (e.g., `@isa/core/config`)
- **Project Names**: Can be found in each library's `project.json` file

## Development Workflow Tips
- Always use `npx nx run` pattern for executing tasks
- Include `--skip-cache` flag when running tests to ensure fresh results
- Use Nx's affected commands to optimize CI/CD pipelines
- Project graph visualization helps understand dependencies: `npx nx graph`

## Development Notes
- Use start target to start the application. Only one project can be started: isa-app
- Make sure to have a look at @docs/guidelines/testing.md before writing tests
- Make sure to add e2e attributes to the html. Those are important for my colleagues writen e2e tests
- Guide for the e2e testing attributes can be found in the testing.md 
- When reviewing code follow the instructions @.github/review-instructions.md