ApprovalManager

• ApprovalManager
  • Overview
  • Data Structure
    • State Schema
    • Enums and Types
    • Additional Structures
  • Core Functionality
    • Main Feature Groups
    • Large Approval Support
  • API Methods
    • Approval Operations
  • Key Features
  • Service Architecture
    • ApprovalFetcher Service

Overview

The ApprovalManager class provides centralized approval workflow management for all entity types in the system. It serves as the backbone for approval processes across Member, Company, Tier, SystemEmail, and other entities that require approval workflows.

General Purpose:

• Centralized approval record processing with MongoDB persistence
• Static approval method for cross-class approval handling
• Abstract base class for entity-specific approval managers
• Integration with callback system for post-approval processing
• Singleton architecture with 'default' instance ID

Data Structure

State Schema

interface ApprovalManagerState {
  private: {}
  public: object
}

The ApprovalManager maintains minimal state, with approval records stored in MongoDB for scalability and persistence across the distributed system.

Enums and Types

enum ApprovalType {
  AUTO = 'auto',
  MANUAL = 'manual'
}

enum ApprovalStatus {
  PENDING = 'pending',
  APPROVED = 'approved',
  REJECTED = 'rejected'
}

enum ApprovalSpecificActors {
  AUTO_APPROVE = 'auto_approve'
}

enum StateManagerActorType {
  PROGRAM_MANAGEMENT_USER = 'program_management_user',
  DEVELOPER = 'developer',
  SYSTEM = 'system',
  MEMBER = 'member'
}

Additional Structures

interface ApprovalRecord {
  id: string
  event: string
  instanceId: string
  entityId: string
  approvalStatus: ApprovalStatus
  entityOldStatus: any
  entityNewStatus: any
  approvalType: ApprovalType
  jsonPatch: ExtendedJSONPatchOperation[]
  isLargeApproval: boolean  // Indicates if jsonPatch is stored externally
  actor: StateManagerActor
  approvers: string[]
  approveCallback?: ApproveCallback
  rejectCallback?: ApproveCallback
  approvedAt?: Date
  approvedBy?: ApprovalActor
  additionalData: any
  createdAt: Date
  updatedAt: Date
}

interface ApprovalRecordInDatabase {
  _id: string
  // ... all ApprovalRecord fields
  largeApprovalPath?: string  // Path to RDK file containing large jsonPatch data
}

interface LargeApprovalData {
  jsonPatch: ExtendedJSONPatchOperation[]
}

interface ApproveCallback {
  event: string
  classId: ClassKey
  instanceId: string
  methodName: string
}

interface ApprovalActor {
  id: string
  type: StateManagerActorType | ApprovalSpecificActors
  name?: string
  roles?: string[]
}

Core Functionality

Main Feature Groups

• Approval Record Processing: Static approve() method handles approval workflow completion and callback execution
• Abstract Approval Management: Base ApprovalManager service class extended by entity-specific approval managers
• Callback System: Configurable approve/reject callbacks for entity-specific post-approval processing
• Role-based Authorization: Validates approver eligibility based on roles and permissions
• MongoDB Persistence: Approval records stored in dedicated MongoDB collection for scalability
• Auto-approval Support: Automatic approval processing for system-driven approval workflows

Large Approval Support

• Size Management: Automatically handles jsonPatch arrays exceeding the size limit (10KB)
• Automatic Detection: System automatically detects when jsonPatch size exceeds threshold during approval creation
• External Storage: Stores large jsonPatch arrays in RDK file storage (separate from MongoDB)
• Transparent Retrieval: ApprovalFetcher.getCompleteApproval() automatically reconstructs complete approval records
• Performance Optimization: Keeps MongoDB documents lean while supporting arbitrarily large approval data
• File Naming: Uses pattern LARGE_APPROVAL_${entityId}_${approvalId}.json for large approval files

API Methods

Approval Operations

• reviewApproval (WRITE) - Review and process an approval request (approve or reject)
  • Uses ApprovalFetcher to retrieve complete approval record including large jsonPatch data
  • Validates approval record exists and is in PENDING status
  • Checks approver eligibility based on roles and permissions
  • Executes configured approval/rejection callback if defined
  • Updates approval status and records approval metadata
  • Persists changes to MongoDB approval collection

Key Features

1. Architecture Pattern: Singleton class with 'default' instance ID and static approval processing
2. Integration Points: Extended by CompanyApprovalManager, MemberApprovalManager, TierApprovalManager, and other entity-specific approval classes
3. Workflow Support: Integration with WorkflowExecuter for automated approval rule processing
4. Security Features: Role-based approval authorization with developer bypass capabilities and actor tracking
5. Data Management: Hybrid storage using MongoDB for metadata and RDK file storage for large jsonPatch arrays (exceeding 10KB)
6. External Integrations: Callback system enables post-approval integration with originating entity classes
7. Performance Features: Static method design for efficient cross-class approval processing with automatic large approval handling
8. Audit/Logging: Complete approval lifecycle tracking with timestamps, actors, status transitions, and JSON patch records
9. Scalability: ApprovalFetcher service provides centralized retrieval logic for complete approval records including large data

Service Architecture

ApprovalFetcher Service

classes/ApprovalManager/services/approval.fetcher.ts centralizes approval retrieval:

• getApprovalRecordFromDatabase(approvalId): Fetches approval record from MongoDB
• getLargeApprovalFile(filename): Retrieves large jsonPatch data from RDK storage
• getCompleteApproval(approvalId): Reconstructs approval record with large jsonPatch data

Used by reviewApproval method and entity-specific approval callback handlers.

Class Relations

The following diagram illustrates how ApprovalManager integrates with other system components: