# PMS Commission Business Logic

## Commission, Fixed Team Allocation, Office Expense & Provident Fund

**Document Type:** Business Logic / Implementation Reference  
**Status:** Updated and Corrected

> **Source of Truth:** Only confirmed business rules in this document may be implemented. Unresolved items must not be assumed by developers.

## 1. Objective

PMS will manage project-based employee commission, fixed team allocation, office expense and provident fund (PF).

The calculation depends on employee eligibility, project contributor assignment, Act As Role, allocation method, client payment, configured commission rules, office expense, PF rules and Company EPS.

## 2. Official Role vs Act As Role

An employee has an **Official Role / Designation**.

A project contributor also has an **Act As Role** for that specific project.

These are separate concepts.

**Act As Role must come from the existing Designation List. There is no separate hard-coded Act As Role list.**

Example:

```text
Employee Official Role = PM
Project Act As Role    = Salesperson
```

The employee remains a PM officially, but project commission/allocation uses the project-specific Act As Role.

## 3. Multiple Contributors

A project can have multiple contributors.

Multiple employees can have the same Act As Role.

Example:

```text
Project A
- PM 1
- PM 2
- Manager 1
- Manager 2
- Closer 1
- Closer 2
- Writer 1
- Writer 2
```

There is currently no confirmed maximum number of employees for one Act As Role.

Every eligible contributor must be evaluated independently.

## 4. Multiple Projects per Employee

One employee can be assigned to multiple projects at the same time.

Example:

```text
Employee = Rahim

Project A -> Manager
Project B -> PM
Project C -> Closer
```

Each project assignment is evaluated independently.

## 5. Cross-Team Contribution

An employee can contribute to a project outside their Home Team.

The project's Act As Role determines the commission/allocation role, not the employee's Official Role.

## 6. Allocation Methods

PMS supports two separate allocation methods:

1. Percentage Commission
2. Fixed Team Allocation

For a given project/team calculation, the configured method determines which method is used. The same calculation must not apply both methods unless Management later confirms that rule.

## 7. Commission Configuration

Commission rate and duration are configurable.

### Current / Default Values

| Role / Designation | Commission Rate | Duration |
|---|---:|---|
| PM | 3% | Lifetime |
| Manager | 1% | Lifetime |
| Closer | 2.75% | 3 Months |
| Proposal Writer | 2.75% | 3 Months |
| Applier / Salesperson | 0.5% | 3 Months |

These values are defaults/current configuration examples and must not be hard-coded.

Management can configure applicable commission percentage, commission duration and active/inactive status.

## 8. Project Dates

Every project has:

```text
Project Start Date
Project End Date
```

These define the project lifecycle.

**Project Start Date is not the reference point for commission duration.**

## 9. Client Payment Trigger

Commission is not calculated merely because a project is created, started or invoiced.

Commission calculation starts after the client payment is **received / cleared**.

The commission duration reference date is the **Client Payment Received / Cleared Date**.

Example:

```text
Project Start Date = January 1
Client Payment Cleared = January 15

Commission reference date = January 15
```

## 10. Commission Duration

For a finite commission duration such as 3 Months, the applicable commission period is measured from the client payment date.

After the configured duration ends, normal commission for that finite-duration role stops.

Lifetime roles continue according to their configuration.

The exact date-boundary convention for a three-month period is still unresolved unless Management specifies it.

## 11. Employee Probation Rule

Employees in probation are not commission eligible.

After probation is completed, they may become eligible according to project, contributor, role and configuration rules.

## 12. Commission Base Amount

The financial flow is:

```text
Client Gross Payment
    -> Applicable Platform / Payment Charges
    -> Net Amount
    -> Dynamic Office Expense
    -> Final Commission Base Amount
```

The commission module does not need to own the detailed source/integration mechanism for platform/payment charges. It consumes the applicable cleared payment and charge values provided by the appropriate financial/payment flow.

## 13. Office Expense

Office Expense is dynamic and percentage-based.

Management configures the Office Expense percentage. It must not be hard-coded.

Formula:

```text
Office Expense Amount
= Net Amount After Platform/Payment Charges
  x Configured Office Expense %

Final Commission Base
= Net Amount After Platform/Payment Charges
  - Office Expense Amount
```

## 14. Percentage Commission Formula

```text
Commission Amount
= Final Commission Base Amount
  x Configured Commission Percentage
```

Example:

```text
Gross Payment = $1,000
Platform/Payment Charges = $120
Net Amount = $880
Office Expense = 10%
Office Expense Amount = $88
Final Commission Base = $792
Closer Rate = 2.75%
Commission = $792 x 2.75% = $21.78
```

## 15. Fixed Team Allocation

Fixed Team Allocation is separate from Percentage Commission.

The Fixed Team Allocation role budget is configured as a **percentage of the applicable team budget**, not as a fixed dollar amount.

Example:

```text
Team Budget = $100

Manager = 50%
PM = 20%
Writer = 15%
Closer = 15%
```

Result:

```text
Manager Pool = $50
PM Pool = $20
Writer Pool = $15
Closer Pool = $15
```

Formula:

```text
Role Allocation Amount
= Team Budget x Configured Role Allocation %
```

## 16. Equal Distribution within the Same Fixed Team Role

Multiple employees can belong to the same fixed allocation role.

The role allocation amount is equally distributed among eligible employees in that role.

Example:

```text
Manager Pool = $50
Managers = Manager 1, Manager 2

Manager 1 = $25
Manager 2 = $25
```

Formula:

```text
Per Employee Allocation
= Role Allocation Amount
  / Number of Eligible Employees in the Role
```

The same rule applies to PM, Writer, Closer or any other configured designation.

## 17. Fixed Allocation Example

```text
Team Budget = $100
PM = 20%
Manager = 50%
Writer = 15%
Closer = 15%
```

If there are 2 PMs, 2 Managers, 1 Writer and 2 Closers:

```text
PM Pool = $20
PM 1 = $10
PM 2 = $10

Manager Pool = $50
Manager 1 = $25
Manager 2 = $25

Writer Pool = $15
Writer 1 = $15

Closer Pool = $15
Closer 1 = $7.50
Closer 2 = $7.50
```

## 18. Percentage Commission vs Fixed Allocation

For the same project/team calculation, the configured allocation method is either:

```text
Percentage Commission
```

or

```text
Fixed Team Allocation
```

Do not mix the two methods unless Management explicitly changes the rule.

## 19. PF Objective

PF is linked to the commission lifecycle.

For finite-duration roles such as Writer, Sales/Approval and Closer, commission is paid for the configured 3-month period. When that commission period ends, the commission stops and the stopped commission amount becomes the PF calculation source.

## 20. PF Role-Based Dynamic Percentage

PF percentage is dynamic and configured by role/designation.

Example values are illustrative only:

| Role | PF Percentage |
|---|---:|
| PM | 2.75% |
| Manager | Management Configured |
| Writer | Management Configured |
| Closer | Management Configured |
| Sales / Approval | Management Configured |

**PF role percentages do not have to total 100%.**

Management decides the PF percentage for each applicable role independently.

## 21. PF Calculation

For each applicable role:

```text
Role PF Amount
= Stopped Commission Amount
  x Configured PF Percentage
```

Example:

```text
Stopped Commission Amount = $1,000
Writer PF = 2%

Writer PF = $1,000 x 2% = $20
```

Where multiple eligible fixed-team members share the same role allocation, the applicable role amount is distributed equally among those members according to the fixed-team member distribution rule.

## 22. PF Maturity / Eligibility Period

PF matures after a configurable number of years.

Example:

```text
PF Maturity Period = 4 Years
```

Management can later change the configured threshold.

The maturity period must not be hard-coded.

## 23. Employee Leaves Before PF Maturity

If an employee leaves before the configured PF maturity period, the employee is not automatically entitled to the full PF amount.

Management decides how much will be paid.

Example:

```text
PF Fund = $10,000
Employee leaves before maturity
Management decides payout = $6,000
```

## 24. PF Disbursement

PF disbursement is manually controlled by Management.

The system must support Management entering the actual disbursement amount and preserving the disbursement history.

```text
PF Accrued
    -> Maturity / Eligibility Check
    -> Management Review
    -> Manual Disbursement Amount
    -> Disbursement History
```

## 25. Company EPS

After PF calculation, any remaining balance is saved as **Company EPS**.

Formula:

```text
Company EPS
= PF Source Amount
  - Total PF Amount Allocated
```

Example:

```text
PF Source Amount = $1,000
Total PF Allocation = $102.50
Company EPS = $897.50
```

## 26. Company EPS Project-wise and Team-wise Storage

Company EPS must be stored in the database with project and team association.

Logical structure:

```text
Company
  -> Project
     -> Team
        -> Company EPS
```

Management must be able to identify the project/team from which the EPS was generated.

## 27. End-to-End Financial Flow

```text
Client Gross Payment
    -> Platform / Payment Charges
    -> Net Payment
    -> Dynamic Office Expense
    -> Final Commission Base
    -> Allocation Method
       -> Percentage Commission
       OR
       -> Fixed Team Allocation
    -> Commission Paid
    -> Finite Commission Duration Ends
    -> Commission Stops
    -> Stopped Commission Amount
    -> Role-based PF Percentage
    -> PF Amount
    -> Remaining Balance
    -> Company EPS (Project + Team wise)
    -> PF Maturity Period
    -> Management Disbursement Decision
    -> PF Disbursement
```

## 28. Historical Configuration Rule

Historical commission, fixed allocation, PF and EPS calculations must not change automatically when Management changes configuration later.

This applies to:

- Commission Rate
- Commission Duration
- Office Expense Percentage
- Fixed Team Allocation Percentage
- PF Percentage
- PF Maturity Period where historical records require preservation

Calculation-time values should be preserved with the relevant transaction/history record.

## 29. Required Transaction History

Commission history should preserve applicable information such as:

```text
Employee
Project
Team
Project Contributor
Act As Role / Designation
Client Payment Reference
Payment Cleared Date
Allocation Method
Commission Base Amount
Commission Rate Used
Commission Duration
Commission Amount
Calculation Date
```

Fixed allocation history should preserve the applicable team budget, role allocation percentage, role allocation amount, eligible employee count and per-employee allocation.

PF history should preserve the applicable employee, project, team, role, PF source amount, PF percentage, PF amount, maturity date, disbursement information and Company EPS amount.

Exact database structure must follow the existing PMS architecture and avoid duplicate tables/models/migrations where equivalent structures already exist.

## 30. Backend Responsibility

Backend is the financial calculation source of truth.

It must handle:

- Employee eligibility and probation
- Project contributor validation
- Designation-based Act As Role
- Multiple project assignments
- Commission configuration
- Payment-triggered duration calculation
- Office Expense
- Percentage Commission
- Fixed Team Allocation
- Equal distribution among same-role fixed-team members
- PF calculation
- PF maturity/eligibility
- Management-controlled PF disbursement
- Company EPS
- Historical transaction preservation

## 31. Frontend Responsibility

Frontend provides:

- Commission configuration UI
- Office Expense configuration UI
- Fixed Team Allocation configuration UI
- PF configuration UI
- Project contributor management
- Act As Role selection from Designation List
- Commission history
- Fixed allocation history
- PF history and maturity status
- PF disbursement information
- Company EPS reporting

Frontend must not be the authoritative financial calculation source.

## 32. Architecture Principle

Inspect the existing PMS architecture first.

Preferred flow:

```text
Controller
  -> Form Request / Validation
  -> Service
  -> Repository
  -> Model
```

Keep business logic in the Service layer and controllers thin. Reuse existing repositories, services, models, configurations and permissions wherever equivalent structures already exist.

## 33. Permissions

Inspect existing PMS permission conventions first.

Reuse existing permissions when possible. Add only the minimum required permissions for:

- Commission Configuration
- Commission Management
- Fixed Team Allocation Configuration
- PF Configuration
- PF Management
- PF Disbursement
- Company EPS Management

Exact permission slugs must follow project conventions.

## 34. Unresolved / Not Confirmed

The following must remain unresolved until Management confirms them:

1. Exact technical source/API of platform and payment charges.
2. Exact refund/chargeback handling workflow.
3. Exact rounding/decimal precision rule.
4. Exact duplicate-payment prevention rule.
5. Exact date-boundary convention for a 3-month commission period.
6. Exact historical treatment if configuration changes while an existing finite commission period is still running.

No developer may invent assumptions for these items.

## 35. Final Business Rule Summary

| Area | Confirmed Rule |
|---|---|
| Official Role | Employee's existing Designation |
| Act As Role | From the same Designation List |
| Separate Act As Role List | No |
| Multiple Contributors | Allowed |
| Same Role Multiple Employees | Allowed |
| One Employee Multiple Projects | Allowed |
| Cross-Team Contribution | Allowed |
| Allocation Method | Percentage Commission OR Fixed Team Allocation |
| Commission Rate | Configurable |
| Commission Duration | Configurable |
| Commission Duration Reference | Client Payment Received / Cleared Date |
| Probation Employee | Not commission eligible |
| Office Expense | Dynamic percentage |
| Fixed Team Allocation | Role budget as percentage of Team Budget |
| Same Fixed Role | Equal distribution among eligible members |
| PF Source | Stopped commission amount for applicable finite-duration roles |
| PF Percentage | Dynamic per role |
| PF Percentage Total = 100% | Not required |
| PF Maturity | Dynamic/configurable years |
| Early Exit Before Maturity | Management decides payout |
| PF Disbursement | Manual Management decision |
| Remaining PF Balance | Company EPS |
| EPS Storage | Project-wise + Team-wise |
| Historical Records | Must remain unchanged |
| Backend | Financial source of truth |

## 36. Core Principle

```text
Employee Eligibility
    + Project Assignment
    + Act As Role from Designation List
    + Allocation Method
    + Client Payment Received/Cleared
    + Applicable Charges
    + Dynamic Office Expense
    + Configured Commission / Allocation
    = Commission / Fixed Team Allocation
```

For applicable finite-duration roles:

```text
Commission Stops
    -> Stopped Commission Amount
    -> Role-based PF Percentage
    -> PF Amount
    -> Remaining Balance
    -> Company EPS
```

PF lifecycle:

```text
PF Accrued
    -> Configured Maturity Period
    -> Eligible / Mature
    -> Management Review
    -> Manual Disbursement
```

**Never hard-code business percentages, durations or maturity periods. Use configuration and preserve historical calculation values.**