# Contact Management Module

This module provides comprehensive contact management functionality for the ACoreX Platform, supporting both individual and organizational contacts with dynamic contact methods, addresses, categorization, and relationship mapping.

## Overview

The Contact Management module enables organizations to maintain detailed contact records with flexible contact methods, structured addresses with geographic support, and complex relationship mapping between contacts. It supports both personal and business contacts with comprehensive metadata and categorization.

## Core Features

- **Unified Contact Management**: Single entity supporting individuals and organizations
- **Dynamic Contact Methods**: Flexible contact methods with type-based validation
- **International Address Support**: Structured address format with map integration
- **Contact Relationships**: Map relationships between contacts (family, business, etc.)
- **Categorization System**: Flexible contact types and sources for organization
- **Geographic Integration**: Map widget support for address coordinates
- **Validation & Verification**: Contact method verification and validation rules

## Entity Architecture

The module consists of 8 interconnected entities organized in a hierarchical structure:

```
Contact (Main Entity)
├── ContactType (Lookup)
├── ContactSource (Lookup)
├── ContactMethod (Related)
│   └── ContactMethodType (Lookup with Regex)
├── ContactAddress (Related)
│   └── AddressType (Lookup)
└── ContactRelationship (Related)
```

## Entity Definitions

### 1. Contact (Main Entity)

The primary entity representing individuals or organizations with core contact information.

**Key Properties:**

- `displayName`: Primary display name
- `firstName`, `lastName`: Individual names
- `title`, `jobTitle`: Professional titles
- `company`: Organization affiliation
- `contactTypeId`: Type classification
- `contactSourceId`: Source tracking
- `priority`: Contact priority level
- `status`: Current status
- `isVip`: VIP designation
- `notes`: Additional notes
- `lastContactDate`: Last interaction date

**Sample Data:**

```json
{
  "id": "c1",
  "displayName": "John Smith",
  "firstName": "John",
  "lastName": "Smith",
  "title": "Mr.",
  "jobTitle": "Software Engineer",
  "company": "Tech Solutions Inc.",
  "contactTypeId": "ct1",
  "contactSourceId": "cs1",
  "priority": "High",
  "status": "Active",
  "isVip": true,
  "notes": "Key technical contact for platform integration",
  "lastContactDate": "2024-01-15T10:30:00Z"
}
```

### 2. ContactType (Lookup Entity)

Categorizes contacts by type (Individual, Organization, Vendor, Client, etc.).

**Key Properties:**

- `name`: Type name
- `description`: Type description
- `icon`: FontAwesome icon
- `isDefault`: Default selection
- `isActive`: Active status
- `order`: Display order

**Sample Data:**

```json
[
  {
    "id": "ct1",
    "name": "Individual",
    "description": "Personal contact",
    "icon": "fa-light fa-user",
    "isDefault": true,
    "isActive": true,
    "order": 1
  },
  {
    "id": "ct2",
    "name": "Organization",
    "description": "Company or organization",
    "icon": "fa-light fa-building",
    "isDefault": false,
    "isActive": true,
    "order": 2
  },
  {
    "id": "ct3",
    "name": "Vendor",
    "description": "Service provider or supplier",
    "icon": "fa-light fa-truck",
    "isDefault": false,
    "isActive": true,
    "order": 3
  }
]
```

### 3. ContactSource (Lookup Entity)

Tracks the source or origin of contact acquisition.

**Key Properties:**

- `name`: Source name
- `description`: Source description
- `icon`: FontAwesome icon
- `isDefault`: Default selection
- `isActive`: Active status
- `order`: Display order

**Sample Data:**

```json
[
  {
    "id": "cs1",
    "name": "Website",
    "description": "Contact form submission",
    "icon": "fa-light fa-globe",
    "isDefault": true,
    "isActive": true,
    "order": 1
  },
  {
    "id": "cs2",
    "name": "Referral",
    "description": "Referred by existing contact",
    "icon": "fa-light fa-user-plus",
    "isDefault": false,
    "isActive": true,
    "order": 2
  },
  {
    "id": "cs3",
    "name": "Event",
    "description": "Met at conference or event",
    "icon": "fa-light fa-calendar-days",
    "isDefault": false,
    "isActive": true,
    "order": 3
  }
]
```

### 4. ContactMethodType (Lookup with Validation)

Defines contact method types with regex validation patterns.

**Key Properties:**

- `name`: Method type name
- `validationRegex`: Validation pattern
- `placeholder`: Input placeholder
- `isActive`: Active status

**Sample Data:**

```json
[
  {
    "id": "cmt1",
    "name": "Email",
    "validationRegex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
    "placeholder": "example@domain.com",
    "isActive": true
  },
  {
    "id": "cmt2",
    "name": "Phone",
    "validationRegex": "^[\\+]?[1-9]?[0-9]{7,15}$",
    "placeholder": "+1-555-123-4567",
    "isActive": true
  },
  {
    "id": "cmt3",
    "name": "LinkedIn",
    "validationRegex": "^https://www\\.linkedin\\.com/in/[a-zA-Z0-9-]+/?$",
    "placeholder": "https://www.linkedin.com/in/username",
    "isActive": true
  },
  {
    "id": "cmt4",
    "name": "Skype",
    "validationRegex": "^[a-zA-Z][a-zA-Z0-9._-]{5,31}$",
    "placeholder": "skype_username",
    "isActive": true
  }
]
```

### 5. ContactMethod (Related Entity)

Dynamic contact methods linked to contacts with type-based validation.

**Key Properties:**

- `contactId`: Parent contact reference
- `methodTypeId`: Method type reference
- `value`: Contact method value
- `isPrimary`: Primary method flag
- `isVerified`: Verification status
- `notes`: Additional notes

**Sample Data:**

```json
[
  {
    "id": "cm1",
    "contactId": "c1",
    "methodTypeId": "cmt1",
    "value": "john.smith@techsolutions.com",
    "isPrimary": true,
    "isVerified": true,
    "notes": "Work email - primary contact"
  },
  {
    "id": "cm2",
    "contactId": "c1",
    "methodTypeId": "cmt2",
    "value": "+1-555-123-4567",
    "isPrimary": true,
    "isVerified": true,
    "notes": "Mobile phone"
  },
  {
    "id": "cm3",
    "contactId": "c1",
    "methodTypeId": "cmt3",
    "value": "https://www.linkedin.com/in/johnsmith-dev",
    "isPrimary": false,
    "isVerified": false,
    "notes": "Professional LinkedIn profile"
  }
]
```

### 6. AddressType (Lookup Entity)

Categorizes address types (Home, Work, Billing, Shipping, etc.).

**Key Properties:**

- `name`: Address type name
- `description`: Type description
- `icon`: FontAwesome icon
- `isDefault`: Default selection
- `isActive`: Active status
- `order`: Display order

**Sample Data:**

```json
[
  {
    "id": "at1",
    "name": "Work",
    "description": "Business office address",
    "icon": "fa-light fa-building",
    "isDefault": true,
    "isActive": true,
    "order": 1
  },
  {
    "id": "at2",
    "name": "Home",
    "description": "Residential address",
    "icon": "fa-light fa-home",
    "isDefault": false,
    "isActive": true,
    "order": 2
  },
  {
    "id": "at3",
    "name": "Billing",
    "description": "Billing address",
    "icon": "fa-light fa-credit-card",
    "isDefault": false,
    "isActive": true,
    "order": 3
  }
]
```

### 7. ContactAddress (Related Entity)

Structured international addresses with geographic coordinates support.

**Key Properties:**

- `contactId`: Parent contact reference
- `addressTypeId`: Address type reference
- `street1`, `street2`: Street address lines
- `city`, `state`, `country`: Geographic location
- `postalCode`: Postal/ZIP code
- `coordinates`: Map coordinates (lat,lng)
- `isPrimary`: Primary address flag
- `notes`: Additional notes

**Sample Data:**

```json
[
  {
    "id": "ca1",
    "contactId": "c1",
    "addressTypeId": "at1",
    "street1": "123 Tech Boulevard",
    "street2": "Suite 456",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "postalCode": "94107",
    "coordinates": "37.7749,-122.4194",
    "isPrimary": true,
    "notes": "Main office building, parking available"
  },
  {
    "id": "ca2",
    "contactId": "c1",
    "addressTypeId": "at2",
    "street1": "789 Residential Street",
    "street2": "Apt 12B",
    "city": "Oakland",
    "state": "California",
    "country": "United States",
    "postalCode": "94610",
    "coordinates": "37.8044,-122.2711",
    "isPrimary": false,
    "notes": "Home address"
  }
]
```

### 8. ContactRelationship (Related Entity)

Maps relationships between contacts (family, business, professional).

**Key Properties:**

- `contactId`: Primary contact reference
- `relatedContactId`: Related contact reference
- `relationshipType`: Relationship classification
- `description`: Relationship details
- `isActive`: Active relationship status

**Available Relationship Types:**

- `parent` - Parent
- `child` - Child
- `spouse` - Spouse
- `sibling` - Sibling
- `friend` - Friend
- `colleague` - Colleague
- `business_partner` - Business Partner
- `vendor` - Vendor
- `client` - Client
- `other` - Other

**Sample Data:**

```json
[
  {
    "id": "cr1",
    "contactId": "c1",
    "relatedContactId": "c2",
    "relationshipType": "colleague",
    "description": "Works in the same development team",
    "isActive": true
  },
  {
    "id": "cr2",
    "contactId": "c1",
    "relatedContactId": "c3",
    "relationshipType": "business_partner",
    "description": "Collaboration partner for platform integration",
    "isActive": true
  },
  {
    "id": "cr3",
    "contactId": "c1",
    "relatedContactId": "c4",
    "relationshipType": "client",
    "description": "Key client for enterprise solutions",
    "isActive": true
  }
]
```

### 9. EmergencyContactCategory (Hierarchical Lookup Entity)

Represents categories for classifying emergency contacts (e.g., Police, Fire, Medical). Supports hierarchical (parent-child) relationships and visual customization.

**Key Properties:**

|     Name      |  Type   | Description                        |
| :-----------: | :-----: | :--------------------------------- |
|     title     | string  | Category title                     |
|  description  | string  | Description of the category        |
|   parentId    | string  | Parent category ID (for hierarchy) |
| childrenCount | number  | Number of direct child categories  |
|     icon      | string  | FontAwesome icon                   |
|     color     | string  | Category color (HEX)               |
|   priority    | number  | Display priority                   |
|   isActive    | boolean | Active status                      |
|     order     | number  | Display order                      |

**Sample Data:**

```json
[
  {
    "id": "ecat1",
    "title": "Police",
    "description": "Law enforcement emergency services",
    "icon": "fa-light fa-shield-halved",
    "color": "#1976d2",
    "priority": 1,
    "isActive": true,
    "order": 1
  },
  {
    "id": "ecat2",
    "title": "Fire Department",
    "description": "Fire and rescue services",
    "icon": "fa-light fa-fire-extinguisher",
    "color": "#d32f2f",
    "priority": 2,
    "isActive": true,
    "order": 2
  }
]
```

### 10. EmergencyContact (Public Emergency Number Entity)

Stores public emergency contact numbers (e.g., 911, 112, local hotlines) with rich metadata, categorization, and geographic/availability details.

**Key Properties:**

|         Name         |   Type   | Description                               |
| :------------------: | :------: | :---------------------------------------- |
|         name         |  string  | Emergency service name                    |
|      shortName       |  string  | Short label (e.g., 911, 112)              |
|     description      |  string  | Description of the service                |
|     categoryIds      | string[] | Linked EmergencyContactCategory IDs       |
|     phoneNumber      |  string  | Main emergency phone number               |
|   alternateNumbers   | string[] | Alternate numbers                         |
|      textNumber      |  string  | SMS/text number                           |
|       website        |  string  | Service website                           |
|        email         |  string  | Contact email                             |
|       country        |  string  | Country of service                        |
|        region        |  string  | Region/State                              |
|         city         |  string  | City                                      |
|      isNational      | boolean  | National coverage flag                    |
|      isRegional      | boolean  | Regional coverage flag                    |
|       isLocal        | boolean  | Local coverage flag                       |
|     availability     |  string  | Availability (24/7, business hours, etc.) |
|      languages       | string[] | Supported languages                       |
|    isTextCapable     | boolean  | Supports SMS/text                         |
|  isVideoCallCapable  | boolean  | Supports video calls                      |
|      whenToCall      |  string  | When to call                              |
|    whenNotToCall     |  string  | When NOT to call                          |
|     instructions     |  string  | Special instructions                      |
|       priority       |  number  | Display priority                          |
|       isActive       | boolean  | Active status                             |
|      isVerified      | boolean  | Verification status                       |
|     lastVerified     |   date   | Last verification date                    |
|   showOnDashboard    | boolean  | Show on dashboard                         |
| requiresConfirmation | boolean  | Requires confirmation before calling      |
|     isQuickDial      | boolean  | Mark as quick dial                        |
|    additionalInfo    |  string  | Additional information                    |

**Sample Data:**

```json
[
  {
    "id": "ec1",
    "name": "Police Emergency",
    "shortName": "911",
    "description": "General police emergency number.",
    "categoryIds": ["ecat1"],
    "phoneNumber": "911",
    "country": "United States",
    "isNational": true,
    "availability": "24/7",
    "languages": ["en"],
    "isTextCapable": true,
    "isVideoCallCapable": false,
    "isActive": true,
    "isVerified": true,
    "priority": 1
  },
  {
    "id": "ec2",
    "name": "Fire Department",
    "shortName": "101",
    "description": "Fire and rescue emergency number.",
    "categoryIds": ["ecat2"],
    "phoneNumber": "101",
    "country": "United States",
    "isNational": true,
    "availability": "24/7",
    "languages": ["en"],
    "isTextCapable": false,
    "isVideoCallCapable": false,
    "isActive": true,
    "isVerified": true,
    "priority": 2
  }
]
```

### Relationship: Category & Emergency Contact

- Each **EmergencyContact** can belong to one or more **EmergencyContactCategory** (many-to-many).
- Categories are hierarchical, supporting parent-child relationships for flexible grouping (e.g., "Medical" > "Poison Control").

**Example:**

```json
{
  "category": {
    "id": "ecat1",
    "title": "Police"
  },
  "contacts": [
    {
      "id": "ec1",
      "name": "Police Emergency",
      "categoryIds": ["ecat1"]
    }
  ]
}
```

> 💡 **Tip:** Use these entities to manage public emergency numbers for any country, region, or city, with full support for categorization, localization, and advanced filtering.

## Integration Examples

### Complete Contact Profile

Here's how all entities work together to create a comprehensive contact profile:

```json
{
  "contact": {
    "id": "c1",
    "displayName": "John Smith",
    "firstName": "John",
    "lastName": "Smith",
    "jobTitle": "Senior Software Engineer",
    "company": "Tech Solutions Inc.",
    "contactType": {
      "id": "ct1",
      "name": "Individual",
      "icon": "fa-light fa-user"
    },
    "contactSource": {
      "id": "cs1",
      "name": "Website",
      "icon": "fa-light fa-globe"
    },
    "priority": "High",
    "status": "Active",
    "isVip": true
  },
  "contactMethods": [
    {
      "methodType": { "name": "Email" },
      "value": "john.smith@techsolutions.com",
      "isPrimary": true,
      "isVerified": true
    },
    {
      "methodType": { "name": "Phone" },
      "value": "+1-555-123-4567",
      "isPrimary": true,
      "isVerified": true
    }
  ],
  "addresses": [
    {
      "addressType": { "name": "Work" },
      "street1": "123 Tech Boulevard",
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "postalCode": "94107",
      "isPrimary": true
    }
  ],
  "relationships": [
    {
      "relatedContact": { "displayName": "Jane Doe" },
      "relationshipType": "colleague",
      "description": "Development team member"
    }
  ]
}
```

## Usage & Implementation

### Translation Keys

All entities support internationalization using the `@contact-management:` scope:

```typescript
// Entity titles
'@contact-management:contact.individual-title';
'@contact-management:contact-method.plural-title';
'@contact-management:contact-address.basic-info';

// Field labels
'@contact-management:contact.display-name';
'@contact-management:contact-method.value';
'@contact-management:contact-address.street1';
```

### Widget Integration

The module leverages various ACoreX widgets:

- **Text Widgets**: `AXPWidgetsCatalog.text`, `AXPWidgetsCatalog.largeText`
- **Lookup Widgets**: `AXPWidgetsCatalog.lookup` for entity references
- **Selection Widgets**: `AXPWidgetsCatalog.select` for predefined options
- **Toggle Widgets**: `AXPWidgetsCatalog.toggle` for boolean flags
- **Map Widget**: `AXPWidgetsCatalog.map` for geographic coordinates
- **Number Widgets**: `AXPWidgetsCatalog.number` for ordering and priorities

### Validation Rules

Contact methods include regex-based validation:

```typescript
// Email validation
validationRegex: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$';

// Phone validation
validationRegex: '^[\\+]?[1-9]?[0-9]{7,15}$';

// LinkedIn profile validation
validationRegex: '^https://www\\.linkedin\\.com/in/[a-zA-Z0-9-]+/?$';
```

## Module Structure

```
libs/modules/contact-management/
├── src/
│   ├── lib/
│   │   ├── entities/
│   │   │   ├── contact/
│   │   │   ├── contact-type/
│   │   │   ├── contact-source/
│   │   │   ├── contact-method-type/
│   │   │   ├── contact-method/
│   │   │   ├── address-type/
│   │   │   ├── contact-address/
│   │   │   └── contact-relationship/
│   │   ├── const.ts
│   │   ├── entity.provider.ts
│   │   ├── menu.provider.ts
│   │   ├── permission.provider.ts
│   │   ├── search.provider.ts
│   │   └── contact-management.module.ts
│   └── index.ts
├── README.md
└── ng-package.json
```

## Installation & Setup

1. **Module Registration**: The module auto-registers with lazy loading
2. **Translation Files**: Add to `apps/demo/src/assets/i18n/{locale}/contact-management.json`
3. **Permissions**: Configure via the permission provider
4. **Menu Integration**: Automatically integrated via menu provider

## Contributing

When extending this module:

1. Follow ACoreX entity patterns
2. Use proper widget names from `AXPWidgetsCatalog`
3. Implement proper validation rules
4. Add comprehensive translations
5. Update this documentation

---

> 💡 **Tip:** This module demonstrates advanced ACoreX patterns including dynamic contact methods, geographic integration, and complex entity relationships. Use it as a reference for implementing similar modules.
