Skip to content

Client Management Business Logic

The client management system handles all aspects of client relationships within the Stratpoint Timesheet Application, from onboarding new clients to managing ongoing billing relationships and payment tracking.

How Client Management Works

For Business Development: 1. Create new client records with basic information 2. Set up billing terms and payment configurations 3. Assign engagement managers to client relationships 4. Track new business opportunities and prospects

For Project Managers: 1. Access client information for project setup 2. View client-specific billing rates and terms 3. Monitor client project portfolios 4. Track client engagement history

For Finance Team: 1. Manage client billing configurations 2. Set up payment terms and collection procedures 3. Track client payment history and aging 4. Generate collection notices for overdue payments

System Features: - Comprehensive client profile management - Payment terms and billing configuration - Collection notice automation - Integration with project and revenue systems - Client classification (Local vs Foreign)

Client Profile Management

Client Setup Process

flowchart TD
    A[New Client Request] --> B[Create Client Profile]
    B --> C[Set Payment Terms]
    C --> D[Assign Engagement Manager]
    D --> E[Configure Billing Settings]
    E --> F[Client Ready for Projects]

Essential Client Information

  • Basic Details: Client name, short name, and contact information
  • Business Classification: Local vs Foreign client designation
  • Payment Terms: Net payment days, MFI terms, or custom arrangements
  • Engagement Manager: Assigned relationship manager
  • Industry Classification: Business sector categorization
  • New Business Year: When client relationship started

Client Types and Classifications

  • Active Clients: Current clients with ongoing projects
  • Prospects: Potential clients in sales pipeline
  • Local Clients: Domestic clients (simplified billing/tax)
  • Foreign Clients: International clients (complex tax/currency handling)
  • New Business: Clients acquired in specific years for tracking

Payment Terms and Billing

Payment Term Options

  • Net Terms: Standard payment terms (Net 15, Net 30, etc.)
  • MFI (Monthly First Invoice): Special payment arrangement
  • Custom Terms: Client-specific payment arrangements
  • Immediate Payment: No payment terms, immediate settlement

Billing Configuration

  • Payment Days: Number of days for payment (15, 30, 45, 60 days)
  • Currency Settings: Local or foreign currency billing
  • Tax Configuration: VAT, withholding tax, and other tax settings
  • Invoice Templates: Client-specific invoice formats
  • Remittance Details: Payment instruction and bank details

Collection Management

Collection Notice System

Automated system for tracking and managing overdue payments:

Collection Stages: 1. First Notice: Initial reminder for overdue payment 2. Second Notice: Follow-up reminder with stronger language 3. Final Notice: Final warning before escalation 4. Legal Action: Escalation to legal department

Collection Process Flow

flowchart LR
    A[Invoice Overdue] --> B[Generate Notice]
    B --> C[Send to Client]
    C --> D[Track Response]
    D --> E{Payment Received?}
    E -->|Yes| F[Close Notice]
    E -->|No| G[Escalate Level]
    G --> B

Collection Notice Features

  • Automated Generation: System creates notices based on aging
  • Document Upload: Attach supporting documents to notices
  • Status Tracking: Monitor notice delivery and responses
  • Escalation Management: Progressive collection strategies
  • Payment Tracking: Link payments to specific notices

Client Relationship Management

Engagement Manager Assignment

  • Relationship Ownership: Assigned engagement manager for each client
  • Communication Coordination: Central point of contact
  • Permission Assignment: Automatic permission grants for client access
  • Reporting Responsibility: Client performance and satisfaction tracking

Client Portfolio Management

  • Project Portfolio: All projects associated with client
  • Revenue Tracking: Client-specific revenue and profitability
  • Payment History: Complete payment and collection history
  • Performance Metrics: Client satisfaction and engagement scores

New Business Tracking

  • Acquisition Year: Track when clients were first acquired
  • Business Development: Monitor new client acquisition trends
  • Revenue Attribution: Track revenue from new vs existing clients
  • Growth Analysis: Client portfolio expansion over time

Integration with Other Systems

Project Management Integration

  • Project Assignment: Link projects to specific clients
  • Billing Setup: Inherit client billing terms for projects
  • Resource Allocation: Track resources dedicated to each client
  • Performance Monitoring: Client-specific project performance

Financial System Integration

  • Invoice Generation: Automatic invoice creation based on client terms
  • Payment Processing: Integration with payment systems
  • Revenue Recognition: Client-specific revenue tracking
  • Collection Management: Automated collection notice generation

NetSuite Integration

  • Customer Sync: Synchronize client data with accounting system
  • Invoice Integration: Seamless invoice generation and tracking
  • Payment Reconciliation: Automatic payment matching
  • Financial Reporting: Integrated financial analysis

Technical Implementation Details

For developers and system administrators

Core API Endpoints

Client Management: 

// Client CRUD operations
GET /api/v2/clients                     // List all clients
POST /api/v2/clients                    // Create new client
PUT /api/v2/clients/{id}                // Update client
DELETE /api/v2/clients/{id}             // Delete client

// Client invoice configuration
PUT /api/v2/clients/update-invoice/{client_id}  // Set invoice settings

Collection Notice Management: 

// Collection notice operations
POST /api/v2/collection_notices/getList        // Get collection notices
POST /api/v2/collection_notice                 // Create collection notice
GET /api/v2/collection_notices/delete/{id}/{index}  // Delete notice

// Document management
POST /api/v2/collection_notices/uploadDocs/{projectId}     // Upload documents
POST /api/v2/collection_notices/deleteUploaded            // Delete uploaded files
POST /api/v2/collection_notices/addFileLink/{projectId}    // Add file links

Database Schema

Client Model Structure: 

// Core client fields from Client model
'name' => 'Full client name (required, unique)',
'shortName' => 'Abbreviated client name (required, unique)',
'tin' => 'Tax identification number',
'address' => 'Client business address',
'payment_terms' => 'Payment terms description',
'remittance_details' => 'Payment instruction details',
'vat' => 'VAT registration information',
'location' => 'Local or Foreign classification (required)',
'engagementManagerUserId' => 'Assigned engagement manager ID',
'newBusiness' => 'Year client was acquired',
'paymentTermLabel' => 'Payment term type (Net, MFI, etc.)',
'paymentTermDays' => 'Number of payment days',
'industryId' => 'Industry classification ID',
'isProspectOnly' => 'Whether client is prospect or confirmed'

Collection Notice Model: 

// Collection notice tracking
'paymentMilestoneId' => 'Associated payment milestone',
'noticeLevel' => 'Collection notice level (1st, 2nd, Final)',
'sentDate' => 'Date notice was sent',
'responseDate' => 'Date client responded',
'status' => 'Notice status',
'notes' => 'Collection notes and comments',
'createdBy' => 'User who created the notice',
'escalationDate' => 'Date for next escalation'

Client Validation Rules

Client Creation Validation: 

// Actual validation rules from ClientController
'name' => 'required|min:2|max:191|unique:clients,name,NULL,id,deleted_at,NULL',
'shortName' => 'required|min:2|max:191|unique:clients,shortName,NULL,id,deleted_at,NULL',
'location' => 'required|in:Local,Foreign',
'engagementManagerUserId' => 'nullable|integer',
'newBusiness' => 'bail|nullable|integer|date_format:Y|min:2015',
'paymentTermLabel' => 'nullable',
'paymentTermDays' => 'nullable|integer',
'industryId' => 'nullable|integer'

Business Rules: - Client names must be unique across the system - Location must be either "Local" or "Foreign" - Payment term days only valid for "Net" or "MFI" term labels - New business year must be 2015 or later - Engagement manager assignment grants automatic permissions

Permission System

Client Management Permissions: - Permission 34: Can view client list - Permission 35: Can create new clients - Permission 36: Can update client information - Permission 208: Can view collection notices - Permission 209: Can create/manage collection notices

Access Validation: 

// Permission check pattern for client operations
if(!hasPermission($this->authUser, 34)) {
    return respondAccessNotAllowed($this->title);
}

Filter Options: 

// Client filter implementation
public static function getfilters($all = false, $ownerId = null, $withProspects = false)
{
    $query = Client::whereNull('clients.deleted_at')
        ->orderBy('clients.shortName', 'asc')
        ->select(['clients.id', 'clients.shortName as title', 'clients.name as fullName',
                 'clients.location', 'clients.industryId', 'clients.isProspectOnly']);

    // Filter by project ownership if specified
    if(!$all && $ownerId) {
        $query->distinct()
            ->leftJoin('projects as p', function($join) use ($ownerId){
                $join->on('p.client_id', '=', 'clients.id');
                $join->on('p.ownerUser_id', '=', $ownerId);
            });
    }

    // Include/exclude prospects
    if(!$withProspects) {
        $query->where('clients.isProspectOnly', 0);
    }

    return $query->get();
}

Collection Notice Automation

Collection Notice Generation: 

// Collection notice filtering and search
'selectBusinessUnit' => 'array_comma_separated_integers',
'selectProject' => 'array_comma_separated_integers',
'selectClient' => 'array_comma_separated_integers',
'selectCollectionStatus' => 'array_comma_separated_integers',
'selectCollectionNextStatus' => 'nullable|integer',
'selectCollectionDaysDue' => 'nullable|integer',
'selectMilestoneStatus' => 'in_array_multiple_values:Billed,Paid',
'selectMilestoneId' => 'nullable|integer'

Aging Calculation: Collection notices automatically calculate payment aging based on milestone due dates and current date.

Integration Points

Project Integration: - Projects linked to clients via client_id foreign key - Client billing terms inherited by project setup - Client-specific project filtering and reporting

Payment Milestone Integration: - Collection notices linked to payment milestones - Automatic aging calculation for overdue payments - Collection status affects milestone tracking

NetSuite Integration: - Client data synchronized with NetSuite customer records - Invoice generation uses client billing configuration - Payment reconciliation updates collection status

Engagement Manager Functionality

Automatic Permission Assignment: 

// When engagement manager is assigned
if(isset($inputs['engagementManagerUserId'])){
    $permissionIdEmailMonthlyCto = 140;
    User::addPermissionId($inputs['engagementManagerUserId'], $permissionIdEmailMonthlyCto);
}

Responsibilities: - Primary contact for client relationship - Access to client-specific reports and data - Responsibility for client satisfaction and retention - Authority for client-related decisions

Payment Term Configuration

Payment Term Types: - Net Terms: Standard commercial payment terms - MFI (Monthly First Invoice): Special monthly billing arrangement - Custom: Client-specific payment arrangements

Payment Day Calculation: System automatically calculates due dates based on: - Invoice/milestone billing date - Client payment term configuration - Business day adjustments for weekends/holidays

This client management system is designed for comprehensive customer relationship management with integrated billing, collection, and project management capabilities specific to Stratpoint's business operations.