← Back to Core Modules ← Back to Table of Contents

4.1 Member Lifecycle Management

The Kingdom Management Portal implements a comprehensive member lifecycle management system that automatically tracks members through various states, manages age transitions, evaluates warrant eligibility, and enforces privacy controls. This system is built around the core principle that member data and permissions evolve over time based on both automatic triggers and administrative actions.

Overview

The member lifecycle system handles:

Member Status System

Status Hierarchy

KMP employs a seven-level status system that tracks member states with a focus on age-based access control and verification requirements:

stateDiagram-v2
    [*] --> UnverifiedMinor: New Minor Registration
    [*] --> Active: New Adult Registration
    
    UnverifiedMinor --> MinorMembershipVerified: Membership Verification
    MinorMembershipVerified --> MinorParentVerified: Parent Verification
    MinorParentVerified --> VerifiedMinor: Full Minor Verification
    
    VerifiedMinor --> Active: Age-up to Adult (18+)
    UnverifiedMinor --> Active: Age-up with Verification
    MinorMembershipVerified --> VerifiedMembership: Age-up Process
    MinorParentVerified --> VerifiedMembership: Age-up Process
    
    Active --> Deactivated: Administrative Action
    VerifiedMembership --> Deactivated: Administrative Action
    Deactivated --> Active: Reactivation
    Deactivated --> VerifiedMembership: Reactivation
    
    Active --> VerifiedMembership: Verification Review
    VerifiedMembership --> Active: Status Update
    
    note right of VerifiedMinor
        Minor with full verification
        and login capability
    end note
    
    note left of Deactivated
        No login capability
        or system access
    end note

Status Definitions

1. Active (Member::STATUS_ACTIVE)

2. Deactivated (Member::STATUS_DEACTIVATED)

3. Verified Membership (Member::STATUS_VERIFIED_MEMBERSHIP)

4. Unverified Minor (Member::STATUS_UNVERIFIED_MINOR)

5. Minor Membership Verified (Member::STATUS_MINOR_MEMBERSHIP_VERIFIED)

6. Minor Parent Verified (Member::STATUS_MINOR_PARENT_VERIFIED)

7. Verified Minor (Member::STATUS_VERIFIED_MINOR)

Age-Up Management System

The age-up system automatically manages the transition of minor members to adult status when they reach 18 years of age. This system ensures compliance with organizational policies while maintaining data integrity and proper access controls.

Automatic Detection Process

sequenceDiagram
    participant Save as Member Save Event
    participant Entity as Member Entity
    participant AgeUp as ageUpReview()
    participant Status as Status Update
    participant Warrant as Warrant Review
    
    Save->>Entity: Member data saved
    Entity->>AgeUp: Call ageUpReview()
    AgeUp->>AgeUp: Check age > 17
    AgeUp->>AgeUp: Check current status
    
    alt Status is minor AND age > 17
        AgeUp->>Status: Update to adult equivalent
        AgeUp->>Entity: Clear parent_id
        Note over Status: Minor statuses transition:<br/>- Unverified Minor → Active<br/>- Minor Parent Verified → Active<br/>- Verified Minor → Verified Membership<br/>- Minor Membership Verified → Verified Membership
    end
    
    AgeUp->>Warrant: Trigger warrant eligibility review
    Warrant->>Entity: Update warrantable status

Age-Up Business Rules

Trigger Conditions

Status Transition Matrix

The system uses specific rules for transitioning minor statuses to adult equivalents:

flowchart TD
    A[Age Check: > 17] --> B{Current Status}
    
    B -->|Unverified Minor| C[STATUS_ACTIVE]
    B -->|Minor Parent Verified| C
    B -->|Verified Minor| D[STATUS_VERIFIED_MEMBERSHIP]
    B -->|Minor Membership Verified| D
    B -->|Active| E[No Change]
    B -->|Verified Membership| E
    B -->|Deactivated| E
    
    C --> F[Clear parent_id]
    D --> F
    F --> G[Trigger Warrant Review]

Automatic Actions

  1. Status Update: Changes minor status to appropriate adult equivalent
  2. Parent Relationship Removal: Clears parent_id field (adult members don’t need parental oversight)
  3. Warrant Eligibility Review: Triggers warrantable status recalculation
  4. Permission Updates: Adult permissions become available

Implementation Details

// Age-up detection in Member::ageUpReview()
public function ageUpReview(): void
{
    if (
        $this->status !== self::STATUS_ACTIVE
        && $this->status !== self::STATUS_VERIFIED_MEMBERSHIP
        && $this->status !== self::STATUS_DEACTIVATED 
        && $this->age > 17
    ) {
        // Member has aged up and is no longer a minor
        $this->parent_id = null;
        
        switch ($this->status) {
            case self::STATUS_UNVERIFIED_MINOR:
            case self::STATUS_MINOR_PARENT_VERIFIED:
                $this->status = self::STATUS_ACTIVE;
                break;
                
            case self::STATUS_VERIFIED_MINOR:
            case self::STATUS_MINOR_MEMBERSHIP_VERIFIED:
                $this->status = self::STATUS_VERIFIED_MEMBERSHIP;
                break;
        }
    }
}

Integration Points

Automatic Triggers

The age-up review is automatically triggered during:

No Manual Queue Required

Unlike the fictional system described earlier, KMP’s age-up process is fully automatic and doesn’t require administrative intervention. The system:

Warrant Eligibility System

The warrant eligibility system dynamically evaluates whether members can hold official positions based on multiple criteria including age, membership status, membership currency, and profile completeness.

Eligibility Evaluation Flow

flowchart TD
    A[Member Evaluation Request] --> B{Age Check}
    B -->|Under 18| C[Not Warrantable: Under 18]
    B -->|18 or Over| D{Status Check}
    
    D -->|Not Verified Membership| E[Not Warrantable: Membership Not Verified]
    D -->|Verified Membership| F{Membership Currency}
    
    F -->|Membership Expired| G[Not Warrantable: Membership Expired]
    F -->|Membership Current| H{Legal Name Check}
    
    H -->|Missing First/Last Name| I[Not Warrantable: Legal Name Not Set]
    H -->|Name Complete| J{Address Check}
    
    J -->|Missing Address Fields| K[Not Warrantable: Address Not Set]
    J -->|Address Complete| L{Phone Check}
    
    L -->|Phone Missing| M[Not Warrantable: Phone Not Set]
    L -->|Phone Present| N[WARRANTABLE]
    
    C --> O[Update warrantable = false]
    E --> O
    G --> O
    I --> O
    K --> O
    M --> O
    
    N --> P[Update warrantable = true]
    O --> Q[Store reasons in non_warrantable_reasons]
    P --> R[Clear non_warrantable_reasons]

Eligibility Criteria

Primary Requirements

  1. Age: Must be 18 years or older
  2. Status: Must have STATUS_VERIFIED_MEMBERSHIP status specifically
  3. Membership Currency: Membership must not be expired
  4. Profile Completeness: All required fields must be populated

Required Profile Fields

Evaluation Storage

The system stores eligibility evaluation results in the non_warrantable_reasons array field:

// Example of reasons array when member is not warrantable
[
    "Member is under 18",
    "Membership is not verified", 
    "Legal name is not set",
    "Address is not set",
    "Phone number is not set"
]

// Empty array when member is warrantable
[]

Implementation Example

// Warrant eligibility evaluation in Member::getNonWarrantableReasons()
public function getNonWarrantableReasons(): array
{
    $reasons = [];
    
    // Age check
    if ($this->age < 18) {
        $reasons[] = 'Member is under 18';
        $this->warrantable = false;
    }
    
    // Status check - must be specifically verified membership
    if ($this->status != self::STATUS_VERIFIED_MEMBERSHIP) {
        $reasons[] = 'Membership is not verified';
        $this->warrantable = false;
    } else {
        // Membership expiration check
        if ($this->membership_expires_on == null || $this->membership_expires_on->isPast()) {
            $reasons[] = 'Membership is expired';
            $this->warrantable = false;
        }
    }
    
    // Legal name completeness
    if ($this->first_name == null || $this->last_name == null) {
        $reasons[] = 'Legal name is not set';
        $this->warrantable = false;
    }
    
    // Address completeness
    if ($this->street_address == null || $this->city == null || 
        $this->state == null || $this->zip == null) {
        $reasons[] = 'Address is not set';
        $this->warrantable = false;
    }
    
    // Phone number requirement
    if ($this->phone_number == null) {
        $reasons[] = 'Phone number is not set';
        $this->warrantable = false;
    }
    
    // If no reasons, member is warrantable
    if (empty($reasons)) {
        $this->warrantable = true;
    }
    
    return $reasons;
}

Automatic Updates

The warrant eligibility review is automatically triggered:

The warrantable boolean flag is automatically updated based on the evaluation, providing quick access for warrant request validation.

Privacy and Data Protection

The KMP system implements comprehensive privacy controls that protect member data while enabling appropriate access for organizational operations.

Privacy Levels

classDiagram
    class PrivacyLevel {
        <<enumeration>>
        PUBLIC
        MEMBERS_ONLY
        OFFICERS_ONLY
        BRANCH_OFFICERS_ONLY
        PRIVATE
    }
    
    class DataAccessMatrix {
        +publicData() : object
        +memberData() : object
        +officerData() : object
        +branchOfficerData() : object
        +fullData() : object
    }
    
    class MinorProtection {
        +isMinor() : boolean
        +hasParentalConsent() : boolean
        +getRestrictedFields() : array
        +filterMinorData() : object
    }
    
    Member --> PrivacyLevel : uses
    Member --> DataAccessMatrix : implements
    Member --> MinorProtection : enforces

Data Filtering System

The system provides different data views based on the requester’s relationship to the member:

Public Data (Member::publicData())

Available to anonymous users and external systems:

[
    'id' => $this->id,
    'sca_name' => $this->sca_name,
    'title' => $this->title,
    'pronunciation' => $this->pronunciation,
    'branch_name' => $this->branch->name ?? null
]

Member Data (Member::memberData())

Available to authenticated members:

[
    ...publicData(),
    'email_address' => $this->email_address,
    'phone' => $this->phone,
    'address' => $this->address,
    'warrantable' => $this->warrantable,
    'roles' => $this->active_roles
]

Officer Data

Available to officers and administrators:

[
    ...memberData(),
    'legal_name' => $this->legal_name,
    'birth_date' => $this->birth_date,
    'status' => $this->status,
    'warrantable_review' => $this->warrantable_review,
    'audit_trail' => $this->audit_logs
]

Minor Protection System

Special protections for members under 18:

flowchart TD
    A[Data Request] --> B{Is Member Minor?}
    B -->|No| C[Apply Standard Privacy Rules]
    B -->|Yes| D{Has Parental Consent?}
    D -->|No| E[Restrict to Basic Info Only]
    D -->|Yes| F{Requester Authorization Level}
    
    F -->|Public| G[Name and Branch Only]
    F -->|Member| H[Limited Contact Info]
    F -->|Officer| I[Full Consented Data]
    F -->|Legal Guardian| J[Full Data Access]
    
    C --> K[Return Filtered Data]
    E --> K
    G --> K
    H --> K
    I --> K
    J --> K

Minor-Specific Restrictions

  1. Contact Information: Limited visibility of email/phone
  2. Legal Name: Restricted to authorized personnel only
  3. Birth Date: Hidden except for age verification purposes
  4. Photo/Image: Requires explicit parental consent
  5. Activity Participation: Tracked separately with consent requirements

Registration and Verification Workflows

Complete Registration Flow

sequenceDiagram
    participant User as Administrator
    participant Form as Registration Form
    participant Controller as MembersController
    participant Entity as Member Entity
    participant Table as MembersTable
    participant Email as Email Service
    
    User->>Form: Fill out member registration
    Form->>Controller: POST /members/add
    
    Controller->>Controller: Create new entity
    Controller->>Controller: Validate form data
    
    alt Validation errors
        Controller-->>User: Display error messages
    else Validation successful
        Controller->>Entity: Generate password token
        Controller->>Entity: Set mobile card token
        
        Controller->>Controller: Check member age
        alt Age < 18
            Controller->>Entity: Set status = UNVERIFIED_MINOR
        else Age >= 18
            Controller->>Entity: Set status = ACTIVE
        end
        
        Controller->>Table: Save member record
        alt Save successful
            alt Minor member
                Controller->>Email: Send minor registration notification
                Email->>Email: Notify secretary of new minor
                Controller-->>User: Minor registration success message
            else Adult member
                Controller-->>User: Adult registration success message
                Note over User: Member must use "forgot password"<br/>to set their own password
            end
            Controller->>Controller: Redirect to member view
        else Save failed
            Controller-->>User: Save error message
        end
    end

Registration Business Rules

Age-Based Registration Paths

The system handles registration differently based on member age:

Minor Members (Under 18):

Adult Members (18 and Over):

Automatic Field Generation

During registration, the system automatically generates:

Administrative Registration Model

Unlike many systems, KMP uses an administrative registration model:

Verification Queue Management

For minor members, a verification workflow is triggered:

Minor Verification Process

flowchart TD
    A[Minor Registration] --> B[STATUS_UNVERIFIED_MINOR]
    B --> C[Email to Secretary]
    C --> D[Administrative Review]
    D --> E{Verification Decision}
    
    E -->|Approve| F[STATUS_MINOR_MEMBERSHIP_VERIFIED]
    E -->|Require Parent Contact| G[Contact Parent/Guardian]
    
    F --> H[Can Begin Participation]
    G --> I[Parent Verification]
    I --> J[STATUS_MINOR_PARENT_VERIFIED]
    J --> K[Limited Login Access]
    
    K --> L[Full Verification]
    L --> M[STATUS_VERIFIED_MINOR]
    M --> N[Full Minor Access]
    
    N --> O[Age 18 Reached]
    O --> P[Automatic Adult Status]

Email Notification System

The registration system integrates with KMP’s email notification system:

Minor Registration Notifications:

Adult Registration:

No Public Registration Interface

KMP does not implement a public self-registration system. Instead:

Administrative Tools and Reporting

Member Management Dashboard

Administrators have access to comprehensive member management tools:

graph TD
    A[Admin Dashboard] --> B[Verification Queue]
    A --> C[Status Management]
    A --> D[Age-Up Review]
    A --> E[Warrant Eligibility]
    A --> F[Privacy Settings]
    A --> G[Bulk Operations]
    A --> H[Audit Reports]
    
    B --> B1[Pending Registrations]
    B --> B2[Email Verifications]
    B --> B3[Document Reviews]
    
    C --> C1[Status Changes]
    C --> C2[Bulk Updates]
    C --> C3[Suspension Management]
    
    D --> D1[Age-Up Queue]
    D --> D2[Minor Transitions]
    D --> D3[Adult Verifications]
    
    E --> E1[Eligibility Reviews]
    E --> E2[Warrant Blocking]
    E --> E3[Role Conflicts]
    
    F --> F1[Consent Management]
    F --> F2[Data Visibility]
    F --> F3[Minor Protections]
    
    G --> G1[Mass Communications]
    G --> G2[Status Changes]
    G --> G3[Data Exports]
    
    H --> H1[Lifecycle Reports]
    H --> H2[Privacy Audits]
    H --> H3[Security Logs]

Reporting and Analytics

The system provides comprehensive reporting on member lifecycle events:

Standard Reports

  1. Registration Trends: New member registrations over time
  2. Status Distribution: Current status breakdown across membership
  3. Age-Up Analytics: Minor to adult transition patterns
  4. Warrant Eligibility: Summary of warrantable member population
  5. Privacy Compliance: Data access and consent tracking

Custom Queries

Administrators can create custom reports using the query builder interface, with pre-built filters for:

Integration Points

System Integration

The member lifecycle system integrates with multiple KMP components:

  1. Authorization System: Status changes affect permission calculations
  2. Warrant Manager: Eligibility updates trigger warrant reviews
  3. Email Service: Automated notifications for lifecycle events
  4. Audit System: All changes logged for compliance and tracking
  5. Branch Management: Status affects branch-level access and visibility
  6. Activity Plugins: Participation eligibility based on member status

External System Integration

The lifecycle system provides APIs for external integration:

// API endpoints for external systems
GET /api/members/{id}/status        // Current status information
GET /api/members/{id}/eligibility   // Warrant eligibility status
POST /api/members/{id}/verify       // Trigger verification workflow
GET /api/reports/lifecycle          // Lifecycle analytics data

Plugin Extension Points

The system provides hooks for plugins to extend lifecycle functionality:

  1. Status Change Events: Plugins can listen for status transitions
  2. Eligibility Evaluation: Custom criteria can be added to warrant evaluation
  3. Verification Workflow: Additional verification steps can be inserted
  4. Privacy Filters: Custom data filtering rules can be implemented
  5. Notification Templates: Custom email templates and delivery methods

Security Considerations

Data Protection

Privacy Compliance

Authentication Security

This comprehensive member lifecycle management system ensures that KMP maintains accurate, secure, and compliant member data while providing the flexibility needed for complex organizational structures and requirements.