# Person Management Module

This module provides centralized person management functionality for the ACoreX Platform, supporting individual persons with role assignments, relationships, and official identifiers.

## Overview

The Person Management module enables organizations to maintain detailed records of people (called **persons**) that can take on various business roles, have official identifiers, and maintain relationships with other persons. It is the root identity system for all person entities in the platform.

## Core Features

- **Unified Person Records**: Supports individuals in a single structure.
- **Role Management**: Assign multiple business roles (customer, vendor, subcontractor, etc.) to a person.
- **Person Relationships**: Define and manage complex relationships between persons (employs, works-for, client-of, etc.).
- **Official Identifiers**: Maintain validated identification data with configurable types.
- **Identifier Type Management**: Fully configurable types for person identifiers, with validation rules and scoping.

## Entity Architecture

The module consists of 5 interconnected entities:

```
Person (Main Entity)
├── PersonRole (Related)
├── PersonRelationship (Related)
├── PersonIdentifier (Related)
│    └── PersonIdentifierType (Lookup/Config)
```

## Entity Definitions

### 1. AXPPerson (Main Entity)

Represents a root identity for an individual person within the system.

**Key Properties:**

- `displayName`: Primary display name
- `firstName`, `lastName`: Person name fields
- `status`: `'active' | 'inactive' | 'blocked' | 'archived'`
- `roles`: Quick access list of assigned roles
- `tags`, `segments`: Optional categorization
- `primaryLocationId`: Optional denormalized pointer to a main location
- `meta`: Custom metadata

### 2. AXPPersonRole (Related Entity)

Assigns one or more business roles to a person, with optional validity periods.

**Key Properties:**

- `personId`: Reference to `AXPPerson`
- `role`: `'customer' | 'vendor' | 'subcontractor' | 'client' | 'employee' | ...`
- `status`: `'active' | 'inactive'`
- `since`, `until`: Role validity period
- `meta`: Custom metadata

### 3. AXPPersonRelationship (Related Entity)

Defines relationships between two persons.

**Key Properties:**

- `fromPersonId`: Source person
- `toPersonId`: Target person
- `type`: `'employs' | 'works-for' | 'subsidiary-of' | 'parent-of' | 'client-of' | 'vendor-of' | 'member-of' | ...`
- `validFrom`, `validTo`: Relationship validity
- `notes`: Optional description
- `meta`: Custom metadata

### 4. AXPPersonIdentifierType (Lookup Entity)

Represents a configurable type of official identifier that can be assigned to persons.

**Key Properties:**

- `code`: Machine-friendly code (e.g., `passport`, `national-id`, `driving-license`)
- `title`: Human-readable title
- `description`: Optional description
- `scope`: `'person' | 'contact' | 'both'`
- `formatRegex`: Optional regex for value validation
- `minLength`, `maxLength`: Optional length constraints
- `allowedCountries`: Optional ISO country codes
- `isUnique`: Whether this identifier type must be unique
- `isActive`: Active flag

### 5. AXPPersonIdentifier (Related Entity)

Stores a specific identifier assigned to a person.

**Key Properties:**

- `personId`: Reference to `AXPPerson`
- `typeId`: Reference to `AXPPersonIdentifierType`
- `value`: Identifier value
- `country`: Optional ISO country code
- `issuer`: Optional issuing authority
- `validFrom`, `validTo`: Optional validity dates
- `isPrimary`: Whether this is the primary identifier of this type
- `meta`: Custom metadata

