OLOW Hotel ERP

Appearance

Party Module Documentation (Shared Kernel) ​

Overview ​

The Party Module implements the Party Pattern (a subset of the Universal Data Model). It is the single source of truth for Contact Information and Identity. Instead of duplicating name, email, phone, address, photo across staff, customers, and vendors tables, all these entities link to a central parties record.

Architecture ​

Domain Layer (app/Domain/Party) ​

Models (1 Core Model) ​

Party (Party.php) ​
  • Table: parties
  • Description: The human or organization entity.
  • Key Fields:
    • name: Legal Name.
    • email: Primary Email (Unique-ish).
    • phone: Primary Phone (Normalized).
    • address, city, country: Location.
    • photo_url: Avatar.
    • party_type: CUSTOMER | STAFF | VENDOR.

Relationships (Polymorphic-ish) ​

The architecture uses a "Reverse Polymorphic" or "Class Table Inheritance" style approach (physically separate tables linking to parent ID).

1. Customer ​

  • Table: customers
  • Fields: party_id (FK), credit_limit, vip_status.
  • Pattern: 1:1 Relationship. Customer delegates identity queries to Party.

2. Staff ​

  • Table: staff
  • Fields: party_id (FK), base_salary, department_id.
  • Pattern: 1:1 Relationship.

3. Vendor ​

  • Table: vendors
  • Fields: party_id (FK), tax_id, payment_terms.
  • Pattern: 1:1 Relationship.

Audit Findings & Improvements ​

Strengths ​

  • DRY Data: If we add "Social Media Handle" fields, we add them once to Party, and Guests, Staff, and Vendors all get it instantly.
  • Unified Search: Finding "John Doe" is one query on parties table, regardless of whether he is a guest or an employee (or both).
  • Privacy/GDPR: PII (Personally Identifiable Information) is isolated in one table, making "Right to be Forgotten" implementation easier (nuke the Party record -> anonymize the linked operational records).

Issues Identified ​

Major ​

  • Role Isolation: Currently, a person who is both a Staff member and a Customer has TWO Party records (one party_type=STAFF, one party_type=CUSTOMER).
    • Impact: Updating phone number on their Staff profile does NOT update it on their Customer profile.
    • Fix: Allow one Party to have multiple Roles (HasOne Customer AND HasOne Staff).

Minor ​

  • Naming Legacy: Code relies on party_type string 'EMPLOYEE'. The domain has shifted to 'STAFF'. This terminology mismatch creates cognitive load.

Module Version ​

Version: 1.0 (Pattern Implemented) Status: Stable