Hartmut/Nexus
1
0
Fork 0
Code Issues 11 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

rename(phase 1): CapaKraken → Nexus across code, UI, docs, CI (#61)
CI / Architecture Guardrails (push) Successful in 2m38s
Details
CI / Assistant Split Regression (push) Successful in 3m33s
Details
CI / Typecheck (push) Successful in 3m51s
Details
CI / Lint (push) Successful in 5m2s
Details
CI / E2E Tests (push) Has been cancelled
Details
CI / Fresh-Linux Docker Deploy (push) Has been cancelled
Details
CI / Release Images (push) Has been cancelled
Details
CI / Build (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details

Browse Source 
rename(phase 1): CapaKraken → Nexus across code, UI, docs, CI (#61)

Co-authored-by: Hartmut Nörenberg <hn@hartmut-noerenberg.com>
Co-committed-by: Hartmut Nörenberg <hn@hartmut-noerenberg.com>
This commit was merged in pull request #61.
This commit is contained in:
Hartmut Nörenberg
2026-05-21 16:28:40 +02:00
committed by Hartmut
parent d9a7ec0338
commit b41c1d2501
943 changed files with 24548 additions and 16832 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/calculation-reference.md
+86 -79
View File
@@ -1,6 +1,6 @@
# Calculation Reference
How every number in CapaKraken is derived. All monetary values are integer cents. All percentages are 0-100 integers unless noted.
How every number in Nexus is derived. All monetary values are integer cents. All percentages are 0-100 integers unless noted.
---
@@ -8,18 +8,20 @@ How every number in CapaKraken is derived. All monetary values are integer cents
**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` |
| 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
@@ -92,22 +94,23 @@ 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) |
| 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) |
---
@@ -130,10 +133,10 @@ winWeightedCents = round(allocatedCents x winProbability / 100)
**Warning thresholds** (`packages/shared/src/constants/index.ts`):
| Level | Threshold |
|-------|-----------|
| INFO | >= 70% |
| WARNING | >= 85% |
| Level | Threshold |
| -------- | ------------------ |
| INFO | >= 70% |
| WARNING | >= 85% |
| CRITICAL | >= 95% or exceeded |
---
@@ -219,16 +222,16 @@ Lines are aggregated by `discipline + "::" + chapter`.
### 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 |
| 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.
@@ -257,6 +260,7 @@ if shoringRatio > 0:
### Component scores (each 0-100)
**Skill Score:**
```
if no required skills: 100
else:
@@ -269,12 +273,14 @@ else:
```
**Availability Score:**
```
no conflicts: 100
else: max(0, 100 - conflictDays x 10)
```
**Cost Score:**
```
no budget: 50 (neutral)
within budget: 100
@@ -283,6 +289,7 @@ over budget: max(0, round(100 - (ratio - 1) x 100))
```
**Utilization Score:**
```
gap = target - current
gap >= 20: 100
@@ -293,12 +300,12 @@ gap < -20: 0
### Combined score (weights)
| Dimension | Weight |
|-----------|--------|
| Skill | 40% |
| Availability | 30% |
| Cost | 20% |
| Utilization | 10% |
| 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)
@@ -314,13 +321,13 @@ Results sorted descending by total score.
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% |
| 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(
@@ -370,53 +377,53 @@ requiredFTEs = SUM(headcount x demandFteFactor)
### 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 |
| 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 |
| 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 |
| 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 |
| 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 |
---