From 688810d47428ce5e0bbaec6ee607d0d981909624 Mon Sep 17 00:00:00 2001
From: ic-builder <ic-builder@turnsys.com>
Date: Sun, 6 Sep 2026 15:39:50 -0500
Subject: [PATCH] Architecture section 11: capacity planning + margin tracking
 in Dolibarr (#826)

Fleet capacity ledger as virtual stock, reservations as consuming orders,
analytic-accounting margins per tenant class (private), KillBill = billing /
Dolibarr = financial brain. vpperf API identity live on erp.knownelement.com.

https://projects.knownelement.com/issues/826#note-16
---
 docs/ARCHITECTURE.md | 51 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f8dc193..2b55b12 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -195,3 +195,54 @@ identities per the TSGCOO pattern (Cloudron + Bitwarden + Redmine/Gitea/GLPI
 groups). All work filed under #826; CRs for any prod change.
 
 > **Docs live on Discourse — this repo is the executable source of truth.** Perf topic: https://community.turnsys.com/t/328
+
+## 11. 📊 Capacity planning & margin tracking in Dolibarr
+
+ERP landscape: 19 Dolibarr instances exist (one per brand);
+**erp.knownelement.com** is the mothership (v24.0.0, REST API live, perf-org
+API identity `vpperf` — creds `~/.creds/dolibarr-perf.env`). KillBill stays
+the subscription billing engine; Dolibarr is the financial brain where
+capacity, cost, and margin meet.
+
+### Capacity ledger (supply)
+
+- Fleet capacity is derived from ground truth we already collect: GLPI CMDB
+  + dmidecode survey + baseline bundles → per-node vCPU/RAM/NVMe/spindle
+  inventory (ARCHITECTURE §3 table is the seed).
+- Represented in Dolibarr as **virtual stock**: one product per capacity SKU
+  per node class (e.g. `cap-oltp-4c8g-nvme`, `cap-batch-spindle`,
+  `cap-k8s-worker-core`). Stock quantity = bookable units; GLPI drift report
+  reconciles it (the nightly reconcile already exists for CIs — extend to
+  capacity products).
+
+### Reservations (demand)
+
+- Paid reservations (class 1) = Dolibarr customer contracts/order lines that
+  consume capacity stock; KillBill invoices the money, Dolibarr holds the
+  commitment. Utilization % = booked/available per SKU per week.
+- The promotion advisor consumes exactly this: KillBill reservation calendar
+  x projected solar surplus x utilization headroom (§7).
+
+### Margin tracking (profitability)
+
+- **Revenue** per tenant: KillBill (exports/journal) → Dolibarr customer
+  invoices/analytic accounts.
+- **Direct costs** per tenant class: power (both sites — utility bills #827;
+  solar self-consumption at contract rate), hardware amortization (post
+  2026-10-11 purchases), WAN/tailnet overheads.
+- Dolibarr **analytic accounting** (accounts + analytic distribution tables
+  are already present) allocates costs to tenant classes → margin per class
+  per month. PRIVATE dimension: margin numbers are revenue/expense detail —
+  LLC-members-only, never published to the public hub (transparency policy).
+
+### Integration plumbing
+
+- `loop/` baselines + beszel utilization → utilization updater script →
+  Dolibarr API (product stock / extrafields) — read/write via vpperf key.
+- Hub publishes ONLY utilization % and capacity counts (public-safe);
+  margins stay inside the ERP.
+
+API gotchas learned (2026-09-06): table prefix is `dolibarr_` (not `llx_`);
+API auth needs `DOLAPIKEY` header; a cloned user needs explicit
+`dolibarr_user_rights` rows copied (admin flag alone does not grant API
+module rights).