# CLAUDE.md

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

# Colmeia Client - Angular 17 Application

## Project Overview
Angular 17 frontend application for the Colmeia B2B customer service automation platform. This client provides the web interface for customer service agents, administrators, and supervisors to manage omnichannel communications across WhatsApp, Facebook Messenger, Instagram, voice calls, and web chat.

## Key Technologies
- **Angular 17** with standalone components
- **TailwindCSS** for styling with custom theme system using CSS variables
- **Angular Material** for UI components
- **Socket.io** for real-time communication
- **Monaco Editor** for code editing
- **Chart.js** and **ng2-charts** for data visualization
- **RxJS 6** for reactive programming
- **TypeScript 5.2** with strict mode
- **PWA** capabilities with service workers

## Development Commands

### Standard Development
- `npm run serve` - Start development server (standard memory)
- `npm run serve:low-mem` - Start with 3.5GB memory limit
- `npm run serve:low-mem-7gb` - Start with 7GB memory limit
- `npm run serve:unsafe` - Start with host 0.0.0.0 (external access)

### Building
- `node --max-old-space-size=6144 node_modules/@angular/cli/bin/ng build -c production` - Recommended production build command
- `npm run build:gcp-prod` - Production build for GCP
- `npm run build:gcp-devel` - Development build for GCP
- `npm run build:gcp-beta` - Beta environment build
- `npm run build:mobile` - Mobile build with Cordova index
- `npm run build:browser:low-mem` - Browser build with memory optimization

### Component Generation
- `npm run gen:component <path>` - Generate component with translation boilerplate
- `npm run gen:c <path>` - Alias for component generation
- `npm run ngc <path>` - Short alias for component generation

### Translation System
- `npm run t:component` - Generate component translation boilerplate
- `npm run t:domain` - Generate domain translation boilerplate
- `npm run t:enum` - Generate enum translation boilerplate
- `npm run t:c-domain` - Generate common domain translation boilerplate

### Utilities
- `npm run compile:preloader` - Compile preloader components
- `npm run clean` - Clean dist, node_modules, and Angular cache
- `npm run analyze` - Bundle analyzer for optimization

## Project Structure

### Core Directories
- **`src/app/behaviors/`** - Application behavior patterns (web-app, mobile-app, etc.)
- **`src/app/components/`** - Reusable UI components
- **`src/app/services/`** - Business logic and API services
- **`src/app/handlers/`** - Event and interaction handlers
- **`src/app/model/`** - TypeScript models and interfaces
- **`src/app/pipes/`** - Angular pipes for data transformation
- **`src/app/directives/`** - Custom Angular directives
- **`src/app/views/`** - Main application views and pages
- **`src/app/translations/`** - Internationalization system

### Key Features
- **`src/app/chat-single-customer/`** - Single customer chat interface
- **`src/app/att-status-central/`** - Attendant status management
- **`src/app/crm-service-tickets-view/`** - CRM ticket integration
- **`src/environments/`** - Environment-specific configurations

### Assets & Styling
- **`src/assets/scss/`** - SCSS stylesheets and Tailwind imports
- **`src/assets/icons/`** - SVG icons and graphics
- **`tailwind.config.ts`** - Tailwind configuration with custom theme
- **`custom-webpack.config.js`** - Custom webpack configuration

### Material Design Theme System
- **`src/assets/scss/vendors/material/light-theme.scss`** - Complete Material theme with CSS variables for primary, accent, success, info, alert, warn color palettes
- **`src/assets/scss/mat-corrections.scss`** - Material component fixes and improvements (FAB, progress bars, chips, buttons, etc.)
- **`src/assets/scss/global/mat-overrides.scss`** - Extensive Material component customizations and styling overrides

## Development Patterns

### Component Creation
Use the component generator for consistent structure:
```bash
npm run ngc dashboard/analytics-widget
```
This creates:
- Component files with translation setup
- Complete translation boilerplate for all supported languages
- Proper TypeScript interfaces with IntelliSense

### Custom Translation System (Colmeia Translation Architecture)
**📚 Complete Documentation**: `src/app/model/translation/README.md`

This custom system provides component-level translations, domain translations, common domains, enum translations, and full TypeScript integration with the `@ColmeiaTranslation` decorator.


### Styling Approach
- **TailwindCSS** as primary styling framework
- **CSS Variables** for dynamic theming (primary, secondary, success, warn, etc.)
- **Angular Material** for complex UI components
- **Custom breakpoints** including 3xl (1800px)
- **Disabled Preflight** to avoid conflicts with Material

## Environment Configuration
- **Multiple environments** in `src/environments/`
- **GCP deployment** variants (production, development, beta, QA)
- **Mobile configurations** for Cordova builds
- **Local development** with backend integration options

## Build System
- **Custom webpack configuration** for optimizations
- **Preloader compilation** with Rollup for performance
- **Memory-optimized builds** with different heap sizes
- **PWA support** with service workers and manifest
- **Bundle analysis** tools for size optimization

## Testing Approach
- **Manual testing** - no automated unit tests currently
- **E2E testing** structure available in e2e/ directory
- **Development testing** through multiple environment configurations

## Key Services
- **Real-time Communication**: Socket.io integration for live chat
- **Authentication**: JWT-based auth with two-factor support
- **File Management**: Multimedia upload/download with security
- **Notifications**: Push notifications and sound alerts
- **Geolocation**: Location services for customer context
- **Search**: Advanced search across multiple data types

## Performance Considerations
- **Memory management** with configurable heap sizes
- **Lazy loading** with custom preloading strategy
- **Bundle optimization** with webpack customizations
- **Image optimization** with WebP support
- **Service worker** for offline capabilities

## Development Environment
- **Node.js 18.15.0** (Volta configuration)
- **NPM 9.5.0**
- **TypeScript 5.2**
- **Angular CLI 17.3.8**

## Special Features
- **Monaco Editor** integration for code editing
- **React components** integration via reactify system
- **Charts and visualizations** with Chart.js
- **Rich text editing** with Quill and TipTap
- **Voice integration** with Twilio SDK
- **Calendar integration** with FullCalendar
- **Advanced forms** with dynamic validation

## Code Style
- **4 spaces** for TypeScript indentation
- **2 spaces** for HTML/SCSS indentation
- **Strict TypeScript** configuration
- **English** for all code and comments
- **JSDoc comments** for documentation
- **Domain-driven** component organization