generated from coulomb/repo-seed
tegwick
86ce511764
Start ledger January 2025. Record coulomb.social (3.75 EUR/mo) and coulomb.pro (3.00 EUR/mo) as per-domain expense rows. Remove Bubble and placeholder overhead. Add infrastructure reference catalogs; virtual server records pending invoice data.
83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# Coulomb MVP — Liquidity & Cost Requirements
|
|
|
|
## Context
|
|
|
|
Coulomb Social carries **operator infrastructure costs** (domains, virtual
|
|
servers, payment-processing fees, future OpenRouter usage) while **customer
|
|
cost-pass-through billing is not active yet**. Members pay a flat subscription; they are not billed for
|
|
underlying platform spend.
|
|
|
|
The Economic Observatory must make the resulting **liquidity burn** visible.
|
|
|
|
## Requirements
|
|
|
|
### LQ-001 — Expense record ledger (source of truth)
|
|
|
|
Capture every operator expense as an individual record in
|
|
`data/expense_records.json`. Fields: `period`, `vendor`, `amount`, `currency`,
|
|
`cost_class`, `source`.
|
|
|
|
**Never store hand-calculated monthly or cumulative totals in data files.**
|
|
All aggregations must be computed programmatically by `observatory/ledger.py`.
|
|
|
|
### 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
|
|
|
|
Maintain an operator liquidity budget (initial: **€1,000**) and compute
|
|
remaining budget after cumulative **infrastructure** spend minus cumulative net
|
|
member payments received.
|
|
|
|
### LQ-004 — Liquidity position
|
|
|
|
Report whether the project is **burning**, **neutral**, or **generating**
|
|
liquidity each period:
|
|
|
|
- `period_net = net_member_payments - infrastructure_cost`
|
|
- `cumulative_net = sum(period_net)`
|
|
- `remaining_budget = initial_budget + cumulative_net`
|
|
|
|
**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
|
|
|
|
### LQ-005 — No customer cost billing (MVP boundary)
|
|
|
|
Do not allocate platform costs to customer invoices in MVP. Cost attribution
|
|
(OpenRouter per member, usage overage) is observatory-only until a later phase
|
|
introduces customer-visible credits or usage billing.
|
|
|
|
### LQ-006 — Historical dashboard
|
|
|
|
Economics Dashboard must show:
|
|
|
|
- Current-period economics (revenue, platform cost, margin)
|
|
- Cumulative liquidity summary (budget, burn, remaining)
|
|
- 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)
|
|
|
|
| Ledger | Path |
|
|
|--------|------|
|
|
| Budget | `data/budget.json` |
|
|
| Expense records | `data/expense_records.json` |
|
|
| Payment records | `data/payment_records.json` |
|
|
| Membership | `data/membership.json` |
|
|
|
|
Future sprints replace manual records with Bubble, Stripe, and OpenRouter imports
|
|
while preserving the same ledger schema and calculation rules. |