# Party Management Module

This module provides centralized party management functionality for the ACoreX Platform, supporting both individual and organizational parties with role assignments, relationships, and official identifiers.

## Overview

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

## Core Features

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

## Entity Architecture

The module consists of 5 interconnected entities:

```
Party (Main Entity)
├── PartyRole (Related)
├── PartyRelationship (Related)
├── PartyIdentifier (Related)
│    └── PartyIdentifierType (Lookup/Config)
```

## Entity Definitions

### 1. AXPParty (Main Entity)

Represents a root identity, either an individual or an organization, within the system.

**Key Properties:**

- `type`: `'individual' | 'organization'`
- `displayName`: Primary display name
- `firstName`, `lastName`: For individuals
- `legalName`: For organizations
- `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

**Sample Data:**

```json
{
  "id": "p1",
  "type": "organization",
  "displayName": "Tech Solutions Inc.",
  "legalName": "Tech Solutions Incorporated",
  "status": "active",
  "roles": ["vendor", "customer"],
  "tags": ["IT", "Enterprise"],
  "segments": ["B2B"],
  "primaryLocationId": "loc1"
}
```

---

### 2. AXPPartyRole (Related Entity)

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

**Key Properties:**

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

**Sample Data:**

```json
{
  "id": "pr1",
  "partyId": "p1",
  "role": "vendor",
  "status": "active",
  "since": "2024-01-01"
}
```

---

### 3. AXPPartyRelationship (Related Entity)

Defines relationships between two parties.

**Key Properties:**

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

**Sample Data:**

```json
{
  "id": "rel1",
  "fromPartyId": "p1",
  "toPartyId": "p2",
  "type": "client-of",
  "validFrom": "2023-05-01",
  "notes": "Long-term enterprise client"
}
```

---

### 4. AXPPartyIdentifierType (Lookup Entity)

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

**Key Properties:**

- `code`: Machine-friendly code (e.g., `vat`, `company-id`, `passport`)
- `title`: Human-readable title
- `description`: Optional description
- `scope`: `'party' | '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

**Sample Data:**

```json
{
  "id": "idtype1",
  "code": "vat",
  "title": "VAT Number",
  "scope": "party",
  "formatRegex": "^[A-Z]{2}[0-9A-Z]{8,12}$",
  "isUnique": true,
  "isActive": true
}
```

---

### 5. AXPPartyIdentifier (Related Entity)

Stores a specific identifier assigned to a party.

**Key Properties:**

- `partyId`: Reference to `AXPParty`
- `typeId`: Reference to `AXPPartyIdentifierType`
- `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

**Sample Data:**

```json
{
  "id": "pid1",
  "partyId": "p1",
  "typeId": "idtype1",
  "value": "DE123456789",
  "country": "DE",
  "isPrimary": true
}
```
