# Enterprise ERP Specification - Operational & Financial Calculation Engines

This document defines the mathematical models, weighting factors, and processing algorithms for the platform's core performance, accountability, and profitability engines.

---

## 1. Employee Productivity Scoring Engine (PES)

The **Productivity Efficiency Score (PES)** is calculated weekly for each employee. It is dynamic and normalized based on the employee's role (e.g., Engineer vs Sales vs Support).

### The PES Formula:

$$\text{PES} = (W_{sprint} \times S_{sprint}) + (W_{time} \times S_{time}) + (W_{ticket} \times S_{ticket}) + (W_{standup} \times S_{standup})$$

Where:
- **$W_{sprint}, W_{time}, W_{ticket}, W_{standup}$** are weights dynamically configured per role (Sum = 1.0).
- **$S_{sprint}$ (Sprint Deliverables Score)**: Percentage of committed story points marked as "Completed & Approved" during the sprint:
  $$S_{sprint} = \min\left(100, \frac{\text{Story Points Completed}}{\text{Story Points Committed}} \times 100\right)$$
- **$S_{time}$ (Time Efficiency Score)**: Evaluates estimated time vs actual timed seconds:
  $$S_{time} = \max\left(0, 100 - \left| \frac{\text{Actual Hours Logged} - \text{Estimated Hours}}{\text{Estimated Hours}} \times 100 \right|\right)$$
- **$S_{ticket}$ (Operations/Helpdesk SLA Score)**: For customer support and IT engineers:
  $$S_{ticket} = \frac{\text{Tickets Closed within SLA}}{\text{Total Tickets Assigned}} \times 100$$
- **$S_{standup}$ (Accountability & Update Score)**: Evaluates checklist updates and attendance:
  $$S_{standup} = \frac{\text{Check-in Standups Submitted} + \text{On-Time Check-ins}}{\text{Total Working Days}} \times 100$$

### Sample Weights Matrix by Domain:

| Department / Role | $W_{sprint}$ | $W_{time}$ | $W_{ticket}$ | $W_{standup}$ |
| :--- | :---: | :---: | :---: | :---: |
| **Engineering / Product** | 0.50 | 0.30 | 0.00 | 0.20 |
| **IT Support / QA** | 0.20 | 0.20 | 0.50 | 0.10 |
| **Administrative / Operations**| 0.00 | 0.20 | 0.60 | 0.20 |

---

## 2. Employee Accountability & Network Check-In Engine

This engine checks check-in and check-out logs to verify presence and detect anomalies.

1. **IP Network Validation**:
   - Compares the `check_in_ip` and `check_out_ip` with the target `settings.office_ip` subnet (e.g., `192.168.1.0/24` or dedicated office static IP).
   - If IP matches: Sets status flag `network_verified = true`.
   - If IP does not match: Flags as `Remote / WFH`, and check if remote work is pre-approved. If not pre-approved, triggers alert to the Team Lead.
2. **Roadmap Variance Tracker**:
   - A NLP similarity tokenizer compares the morning `plan_morning` text block with the evening `completed_evening` text block.
   - If they list 4 tasks in the morning but only check off 1 in the evening (or if task descriptions show zero correlation), it flags a **Low Completion Warning** (Variance > 60%).

---

## 3. Project Profitability Tracking Engine (PPE)

Calculates the net profitability margin of client-commissioned projects in real-time.

```mermaid
graph TD
    Rev[Gross Project Revenue] -->|Minus| DirectCost[Direct Labor Cost]
    Rev -->|Minus| Exp[Project Direct Expenses]
    DirectCost --> GrossMargin[Gross Profit Margin]
    Exp --> GrossMargin
    GrossMargin -->|Minus| Overhead[Allocated Company Overhead]
    Overhead --> NetMargin[Net Profit Margin]
```

### Calculations:

1. **Gross Revenue ($R_{gross}$)**:
   - *Time & Materials (T&M)*: Sum of billable task times multiplied by employee hourly rates.
     $$R_{gross} = \sum (\text{Logged Billable Seconds} \times \text{Hourly Billing Rate})$$
   - *Fixed Price*: Value of completed and invoiced milestones.
2. **Direct Labor Cost ($C_{labor}$)**:
   - Prorated cost of resources based on time spent:
     $$C_{labor} = \sum_{employee} \left( \frac{\text{Logged Seconds on Project}}{\text{Monthly Total Working Seconds}} \times \text{Base Salary Monthly} \right)$$
3. **Direct Project Expenses ($E_{direct}$)**:
   - Sum of approved expenses associated with the project (e.g., client dinners, server costs, software libraries).
4. **Project Net Margin ($M_{net}$)**:
   - Margin calculation:
     $$\text{Net Profit} = R_{gross} - C_{labor} - E_{direct}$$
     $$M_{net} (\%) = \frac{\text{Net Profit}}{R_{gross}} \times 100$$

---

## 4. Revenue Analytics & Company KPI Engine

Calculates company-wide financials and CRM velocity indicators daily.

- **Cash Runway**: Calculates how long the company can survive on current cash reserves:
  $$\text{Runway (Months)} = \frac{\text{Current Cash Balances (Treasury)}}{\text{Monthly Cash Burn Rate (Payroll + Operational Expenses)}}$$
- **Customer Acquisition Cost (CAC)**: Evaluates marketing spend against won deals:
  $$\text{CAC} = \frac{\text{Total Marketing Spend} + \text{Sales Salaries}}{\text{Number of Closed Won Clients}}$$
- **Monthly Recurring Revenue (MRR)**: Accrued revenue from active retainer contracts.
- **EBITDA Engine**: Earnings Before Interest, Taxes, Depreciation, and Amortization:
  $$\text{EBITDA} = \text{Gross Revenue} - \text{Cost of Services (Direct Labor)} - \text{Operational Expenses (Rent, Software, Assets)}$$