# Calculation Reference

How every number in Planarchy is derived. All monetary values are integer cents. All percentages are 0-100 integers unless noted.

---

## 1. Allocation Costs

**Source:** `packages/engine/src/allocation/calculator.ts`

| Metric | Formula | Notes |
|--------|---------|-------|
| Daily Cost | `round(hoursPerDay x lcrCents)` | LCR = Labor Cost Rate (cents/hour) |
| Total Cost | `round(lcrCents x hoursPerDay x workingDays)` | Mon-Fri only, minus vacation days |
| Working Days | Calendar days minus weekends minus vacations | Sat included only if `includeSaturday=true` |

**Inputs:**
- `lcrCents` — from Resource record (integer cents per hour)
- `hoursPerDay` — from Allocation record
- `startDate` / `endDate` — allocation period

**Edge cases:**
- Null LCR -> cost = 0
- Recurring allocations use `getRecurringHoursForDay()` per-day override
- Availability-aware: capped at resource's available hours for that weekday
- Vacation days block hours completely (reduce to 0 for that day)

---

## 2. Chargeability

### 2a. Allocation-level Chargeability

**Source:** `packages/engine/src/allocation/chargeability.ts`

```
availableHours = SUM(availability[weekday] for each working day in period)
bookedHours    = SUM(min(allocation.hoursPerDay, availability[day]) for each overlapping day)
chargeability  = availableHours > 0 ? min(100, round(bookedHours / availableHours x 100)) : 0
```

- Capped at 100 (overbooking not reflected)
- Only counts days where resource has availability > 0

### 2b. Forecast Chargeability (Chargeability Report)

**Source:** `packages/engine/src/chargeability/calculator.ts`

Per resource per month:

```
For each assignment overlapping the month:
  hours = hoursPerDay x workingDays(in overlap)
  categoryHours[categoryCode] += hours

chg  = min(1, chargeableHours / SAH)
bd   = min(1, bdHours / SAH)
mdi  = min(1, mdiHours / SAH)
...
unassigned = min(1, max(0, SAH - totalAssigned) / SAH)
```

Categories come from the project's `utilizationCategory.code`. All ratios sum to <= 1.0.

### 2c. Group Chargeability (FTE-weighted)

```
groupChg = SUM(fte_i x chg_i) / SUM(fte_i)
```

Returns 0-1 ratio. Used for chapter/team aggregations.

---

## 3. Standard Available Hours (SAH)

**Source:** `packages/engine/src/sah/calculator.ts`

SAH is the denominator for all chargeability ratios.

```
For each day in period:
  if weekend        -> weekendDays++
  else if holiday   -> publicHolidayDays++
  else if absent    -> absenceDays++
  else:
    hoursForDay = getDailyHours(day, baseHours, scheduleRules) x FTE
    totalHours += hoursForDay
    netWorkingDays++

SAH = round(totalHours x 100) / 100
```

**Schedule rules** (e.g. Spain):
- Friday: reduced hours (`fridayHours`)
- Summer period: reduced hours (`summerHours`)
- Default: `regularHours`

**Components returned:**

| Field | Meaning |
|-------|---------|
| calendarDays | Total days (inclusive) |
| weekendDays | Sat + Sun |
| grossWorkingDays | calendarDays - weekendDays |
| publicHolidayDays | Holidays falling on working days |
| absenceDays | Vacations/absences on working days |
| netWorkingDays | Gross - holidays - absences |
| effectiveHoursPerDay | Weighted average including FTE |
| standardAvailableHours | **SAH** (total for period) |

---

## 4. Budget

**Source:** `packages/engine/src/budget/monitor.ts`

```
For each allocation:
  totalCents = dailyCostCents x workingDays(Mon-Fri)

  CONFIRMED/ACTIVE -> confirmedCents += totalCents
  PROPOSED         -> proposedCents  += totalCents

allocatedCents   = confirmedCents + proposedCents
remainingCents   = budgetCents - allocatedCents
utilizationPct   = budgetCents > 0 ? (allocatedCents / budgetCents) x 100 : 0
winWeightedCents = round(allocatedCents x winProbability / 100)
```

**Warning thresholds** (`packages/shared/src/constants/index.ts`):

| Level | Threshold |
|-------|-----------|
| INFO | >= 70% |
| WARNING | >= 85% |
| CRITICAL | >= 95% or exceeded |

---

## 5. Vacation Balance

**Source:** `packages/api/src/router/entitlement.ts`

### Day counting

```
countDays(start, end, isHalfDay) =
  isHalfDay ? 0.5 : round((end - start) / 86400000) + 1
```

Calendar days, inclusive. Half-day always = 0.5.

### Carryover (lazy, on first access)

```
carryover = max(0, prev.entitledDays - prev.usedDays - prev.pendingDays)
new.entitledDays = defaultDays + carryover
```

### Balance sync

```
usedDays    = SUM(countDays(...)) where status=APPROVED and type in [ANNUAL, OTHER]
pendingDays = SUM(countDays(...)) where status=PENDING  and type in [ANNUAL, OTHER]
remaining   = max(0, entitledDays - usedDays - pendingDays)
sickDays    = SUM(countDays(...)) where status=APPROVED and type=SICK  (informational, does not consume balance)
```

---

## 6. Estimates

**Source:** `packages/engine/src/estimate/metrics.ts`

### Per demand line

```
costTotalCents  = round(hours x costRateCents)
priceTotalCents = round(hours x billRateCents)
```

### Estimate summary

```
totalHours      = SUM(line.hours)
totalCostCents  = SUM(line.costTotalCents)
totalPriceCents = SUM(line.priceTotalCents)
marginCents     = totalPriceCents - totalCostCents
marginPercent   = totalPriceCents > 0 ? round(marginCents / totalPriceCents x 100) : 0
```

---

## 7. Effort Rules

**Source:** `packages/engine/src/estimate/effort-rules.ts`

Converts scope items into demand lines:

```
unitCount = case unitMode:
  "per_frame" -> frameCount ?? 1
  "per_item"  -> itemCount ?? 1
  "flat"      -> 1

hours = round(unitCount x hoursPerUnit x 100) / 100
```

Rules match by `scopeType` (case-insensitive). Sorted by `sortOrder`. Unmatched scope items generate warnings.

Lines are aggregated by `discipline + "::" + chapter`.

---

## 8. Experience Multipliers

**Source:** `packages/engine/src/estimate/experience-multiplier.ts`

### Rule matching (hierarchical specificity)

| Specificity | Filters present | Score |
|-------------|-----------------|-------|
| Most specific | chapter + location + level | 7 |
| | chapter + location | 6 |
| | chapter + level | 5 |
| | chapter only | 4 |
| | location + level | 3 |
| | location only | 2 |
| | level only | 1 |
| Least specific | none (global fallback) | 0 |

Highest score wins. Ties broken by order.

### Rate adjustment

```
adjustedCostRate = round(costRateCents x costMultiplier)
adjustedBillRate = round(billRateCents x billMultiplier)
```

### Shoring ratio

```
if shoringRatio > 0:
  onsiteHours   = hours x (1 - shoringRatio)
  offshoreHours = hours x shoringRatio x (1 + additionalEffortRatio)
  adjustedHours = round((onsiteHours + offshoreHours) x 100) / 100
```

---

## 9. Staffing Suggestions

**Source:** `packages/staffing/src/skill-matcher.ts`

### Component scores (each 0-100)

**Skill Score:**
```
if no required skills: 100
else:
  requiredScore = SUM((proficiency/5) x (70/requiredCount)) for matched skills
  if preferred skills exist:
    preferredScore = SUM((proficiency/5) x (30/preferredCount)) for matched
    score = min(100, round(requiredScore + preferredScore))
  else:
    score = min(100, round(requiredScore / 70 x 100))
```

**Availability Score:**
```
no conflicts: 100
else: max(0, 100 - conflictDays x 10)
```

**Cost Score:**
```
no budget:            50 (neutral)
within budget:        100
over budget:          max(0, round(100 - (ratio - 1) x 100))
  where ratio = resourceLCR / budgetLCR
```

**Utilization Score:**
```
gap = target - current
gap >= 20:   100
gap >= 0:    60 + gap x 2
gap >= -20:  max(0, 60 + gap x 2)
gap < -20:   0
```

### Combined score (weights)

| Dimension | Weight |
|-----------|--------|
| Skill | 40% |
| Availability | 30% |
| Cost | 20% |
| Utilization | 10% |

```
total = round(skill x 0.4 + availability x 0.3 + cost x 0.2 + utilization x 0.1)
```

Results sorted descending by total score.

---

## 10. Resource Value Score

**Source:** `packages/staffing/src/value-scorer.ts`

Five dimensions, each normalized to 0-100:

| Dimension | Formula | Weight |
|-----------|---------|--------|
| Skill Depth | `round(avgProficiency / 5 x 100)` | 30% |
| Skill Breadth | `min(100, skillCount x 10)` | 15% |
| Cost Efficiency | `round((1 - lcrCents/maxLcrCents) x 100)` | 25% |
| Chargeability | `max(0, 100 - abs(target - current) x 2)` | 15% |
| Experience | `min(100, round(avgYears x 10))` | 15% |

```
total = clamp(0, 100, round(
  depth x 0.30 + breadth x 0.15 + costEff x 0.25 + chg x 0.15 + exp x 0.15
))
```

Recomputed on demand with 90-day lookback for current chargeability.

---

## 11. Dashboard Metrics

**Source:** `packages/application/src/use-cases/dashboard/`

### Overview

```
totalCostCents     = SUM(dailyCostCents x inclusiveDays) for budget bookings
avgUtilizationPct  = totalBudgetCents > 0 ? round(totalCost / totalBudget x 100) : 0
```

### Peak Times

```
For each allocation, for each day in period:
  bucket[weekKey or monthKey][group] += hoursPerDay

capacityHours = SUM(avgDailyAvailability) x (week=5, month=22)
```

Groups: by project (shortCode), chapter, or resource name.

### Demand Analysis

```
demandFteFactor = percentage > 0 ? percentage/100 : (hoursPerDay/8)
allocatedHours  = SUM(hoursPerDay x inclusiveDays)
requiredFTEs    = SUM(headcount x demandFteFactor)
```

---

## 12. Column Definitions

**Source:** `packages/shared/src/constants/columns.ts`

### Allocation Columns

| Key | Label | Default | Hideable | Derivation |
|-----|-------|---------|----------|------------|
| resource | Resource | visible | no | `assignment.resource.displayName` |
| project | Project | visible | no | `project.shortCode + project.name` |
| role | Role | visible | yes | `allocation.role` (text label) |
| dates | Dates | visible | yes | `startDate -> endDate` formatted |
| hoursPerDay | h/day | visible | yes | `allocation.hoursPerDay` |
| cost | Daily Cost | hidden | yes | `round(hoursPerDay x lcrCents) / 100` in EUR |
| status | Status | visible | yes | PROPOSED / CONFIRMED / ACTIVE / COMPLETED / CANCELLED |

### Resource Columns

| Key | Label | Default | Derivation |
|-----|-------|---------|------------|
| displayName | Name | visible | Direct from DB |
| eid | EID | visible | Employee ID (anonymized when enabled) |
| chapter | Chapter | visible | Organizational unit |
| roles | Roles | visible | From ResourceRole join table |
| chargeability | Chargeability | visible | See Section 2a |
| lcr | LCR | hidden | Labor Cost Rate (cents/hour), requires VIEW_COSTS |
| valueScore | Score | hidden | See Section 10 |
| isActive | Status | visible | Boolean flag |

### Project Columns

| Key | Label | Default | Derivation |
|-----|-------|---------|------------|
| shortCode | Code | visible | Direct from DB |
| name | Name | visible | Direct from DB |
| status | Status | visible | DRAFT / ACTIVE / COMPLETED / CANCELLED |
| orderType | Type | visible | CHARGEABLE / INTERNAL / INVESTMENT |
| dates | Dates | visible | `startDate -> endDate` |
| budget | Budget | hidden | `project.budgetCents / 100` in EUR |
| allocations | Allocations | visible | Count of linked assignments + demands |

---

## 13. Rounding & Precision Rules

| Domain | Rule |
|--------|------|
| Money | Integer cents everywhere. `round(value)` at calculation boundary |
| Hours | 2 decimal places: `round(x * 100) / 100` |
| Percentages | Integer 0-100: `round(ratio * 100)` |
| Scores | Integer 0-100: `round(weighted_sum)`, clamped |
| Days | Integer (or 0.5 for half-day vacations) |
| FTE | Decimal (e.g. 0.8), used as multiplier on SAH |

---

## 14. Constants

**Source:** `packages/shared/src/constants/index.ts`

```
DEFAULT_WORKING_HOURS_PER_DAY = 8

DEFAULT_AVAILABILITY = {
  monday-friday: 8h each
  saturday/sunday: 0h
}

BUDGET_WARNING_THRESHOLDS = { INFO: 70, WARNING: 85, CRITICAL: 95 }

STAFFING_SCORE_WEIGHTS  = { SKILL: 0.4, AVAILABILITY: 0.3, COST: 0.2, UTILIZATION: 0.1 }
VALUE_SCORE_WEIGHTS     = { SKILL_DEPTH: 0.30, BREADTH: 0.15, COST_EFF: 0.25, CHG: 0.15, EXP: 0.15 }
```