Refactor economics to expense-record ledger with correct Bubble cost

Replace pre-aggregated costs.json with expense_records.json (48 line-item
records) and payment_records.json. All monthly and cumulative totals are
computed deterministically in observatory/ledger.py. Correct Bubble.io to
$32/mo (since Feb 2025) — infrastructure €69.44/mo not €72.20.
This commit is contained in:
2026-06-22 02:03:22 +02:00
parent ea2c2c6403
commit 31db9f8f31
12 changed files with 843 additions and 299 deletions

View File

@@ -11,15 +11,20 @@ The Economic Observatory must make the resulting **liquidity burn** visible.
## Requirements
### LQ-001 — Platform cost ledger
### LQ-001 — Expense record ledger (source of truth)
Record monthly platform costs from project start (March 2025), including fixed
infrastructure and payment-provider variable fees when member revenue exists.
Capture every operator expense as an individual record in
`data/expense_records.json`. Fields: `period`, `vendor`, `amount`, `currency`,
`cost_class`, `source`.
### LQ-002 — Member payment ledger
**Never store hand-calculated monthly or cumulative totals in data files.**
All aggregations must be computed programmatically by `observatory/ledger.py`.
Record member subscription payments from first payment month (November 2025),
separate from platform cost accrual.
### LQ-002 — Payment record ledger
Capture member subscription payments in `data/payment_records.json` with gross,
fees, and net amounts per period. Payment-processing totals are summed from
`fees_amount` — not duplicated as expense records.
### LQ-003 — Budget tracking
@@ -36,18 +41,15 @@ liquidity each period:
- `cumulative_net = sum(period_net)`
- `remaining_budget = initial_budget + cumulative_net`
**No double-counting:** payment-processing fees (Stripe) are deducted from net
member payments. They are tracked separately for economics reporting but must
**not** be subtracted again in the liquidity formula.
**No double-counting:** payment-processing fees are deducted from net member
payments. They are summed separately for economics reporting but must **not** be
subtracted again in the liquidity formula.
- `total_platform_cost = infrastructure_cost + payment_processing_cost` (for
gross-margin economics vs gross revenue)
- `cumulative_total_platform_cost` is informational; liquidity burn uses
`cumulative_infrastructure_cost` only
Negative remaining budget means the MVP has consumed more liquidity than the
allocated budget.
### LQ-005 — No customer cost billing (MVP boundary)
Do not allocate platform costs to customer invoices in MVP. Cost attribution
@@ -60,16 +62,22 @@ Economics Dashboard must show:
- Current-period economics (revenue, platform cost, margin)
- Cumulative liquidity summary (budget, burn, remaining)
- Monthly history table from March 2025
- Monthly history table computed from ledgers
### LQ-007 — Deterministic calculation engine
All economics and liquidity figures must be produced by the Python observatory
package (`ledger.py`, `economics.py`). LLM or manual arithmetic must not be the
source of aggregated totals.
## Data sources (current)
| Registry | Path |
|----------|------|
| Ledger | Path |
|--------|------|
| Budget | `data/budget.json` |
| Platform costs | `data/costs.json` (`rate_card` + `monthly_history`) |
| Member payments | `data/revenue.json` |
| Expense records | `data/expense_records.json` |
| Payment records | `data/payment_records.json` |
| Membership | `data/membership.json` |
Future sprints replace manual history with Bubble, Stripe, and OpenRouter imports
while preserving the same liquidity semantics.
Future sprints replace manual records with Bubble, Stripe, and OpenRouter imports
while preserving the same ledger schema and calculation rules.