ISA-Frontend/CLAUDE.md

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

# 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

# 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

# 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

# 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