Qortal-Nextcloud-Integration/docs/engineering/billing-architecture-v1.md

Billing + Credits Architecture v1

1. System boundary

Separate billing orchestration from plugin runtime.

1. Payment System (e.g. Paymenter):
   • plans, checkout, invoices, payments
2. Management Cloud / Credits Service:
   • authoritative credit ledger
   • entitlement state
   • grant workflows
   • treasury + funding automation
3. NuQloud plugin + broker:
   • checks credits/entitlements before write operations
   • records consumption/refunds via management APIs

Nextcloud app should not integrate directly with payment webhooks.

2. Data model (minimum)

2.1 Ledger entries

ledger_entries

1. id
2. instance_id
3. type (grant|purchase|consume|refund|adjustment)
4. credits_delta (signed integer)
5. qort_amount (nullable decimal, reference only)
6. ref (idempotency key)
7. metadata (JSON)
8. created_at

Constraint:

1. unique index on (instance_id, type, ref)

2.2 Balances

instance_balances

1. instance_id (PK)
2. credits_balance
3. updated_at

2.3 Entitlements

instance_entitlements

1. instance_id (PK)
2. plan
3. follower_count
4. capacity_gb
5. status (active|past_due|suspended|cancelled)
6. period_end
7. updated_at

2.4 Grants

intro_grants

1. instance_id (unique)
2. status (pending|approved|rejected|completed)
3. requested_at
4. approved_by
5. approved_at
6. grant_credits
7. ref (request id / tx id)

3. API contract (minimum)

3.1 Billing webhook ingest

POST /billing/webhook/paymenter

1. Verify signature/HMAC.
2. Extract instance_id from trusted metadata.
3. Write idempotent purchase ledger entry.
4. Update entitlement state.
5. Trigger async funding/reconciliation job.

3.2 Balance + entitlement read

1. GET /instances/{id}/billing/summary
2. Returns:
   • balance
   • plan
   • capacity
   • follower targets
   • status

3.3 Consumption

POST /instances/{id}/credits/consume

1. Input:
   • cost_credits
   • ref (publish operation id)
   • metadata
2. Behavior:
   • atomic check and decrement
   • idempotent by ref

3.4 Refund

POST /instances/{id}/credits/refund

1. Input:
   • credits
   • ref (failed operation id)
2. Behavior:
   • idempotent compensation entry

3.5 Intro grant request/approval

1. POST /instances/{id}/grants/intro/request
2. POST /instances/{id}/grants/intro/approve
3. POST /instances/{id}/grants/intro/reject

Guardrails:

1. One grant ever per instance.
2. Approval role required.
3. Fixed max grant size.

3.6 Product catalog discovery

POST /api/sovereign/v1/billing/catalog

1. Accepts instance-scoped request plus optional categoryId.
2. Returns canonical catalog contract sc.billing.catalog.v1.
3. Includes normalized subscriptions[] and addons[] for UI rendering.
4. Enables adding/changing purchasable products without plugin updates.

4. Publish-time flow

1. Plugin/broker receives write request.
2. Determine cost in credits.
3. Call consume endpoint with operation ref.
4. Attempt write/publish.
5. On success: done.
6. On failure: call refund endpoint.

Requirements:

1. operation ref must be globally unique.
2. no duplicate charges on retries.

5. Funding and reconciliation

Optional treasury automation keeps publishing identity funded against outstanding credit liabilities.

Reconciliation job:

1. compute required funding from credit liability + safety buffer.
2. compare to instance publishing-wallet balance.
3. queue transfer if below threshold.
4. store tx hash and reconciliation ref.

6. Idempotency and concurrency

Non-negotiable:

1. webhook ingest idempotent.
2. consume/refund idempotent.
3. atomic balance updates (transaction/row lock).
4. no negative balance race conditions.

7. Failure modes + handling

1. Duplicate webhook:
   • ignored by unique (instance_id,type,ref)
2. Payment metadata missing instance_id:
   • reject and quarantine event
3. Publish fails after consume:
   • refund by same operation ref
4. Entitlement expired:
   • block guaranteed-replication features; keep clear error state

8. Operational controls

1. Admin override endpoint for adjustments with audit trail.
2. Export ledger CSV/JSON for audit.
3. Alerting for:
   • low balance
   • funding failures
   • degraded replication below plan target

9. Security controls

1. Verify payment webhooks cryptographically.
2. Restrict webhook endpoint exposure.
3. Separate service credentials for:
   • payment ingest
   • ledger mutation
   • read-only dashboard queries
4. Redact sensitive fields in logs.

10. Implementation phases

1. Phase 1:
   • ledger + balances + entitlements schema
   • summary/read API
2. Phase 2:
   • consume/refund idempotent endpoints
   • broker integration
3. Phase 3:
   • payment webhook ingest + entitlement update
4. Phase 4:
   • intro grant workflow
   • reconciliation/funding jobs
5. Phase 5:
   • dashboards, exports, alerts