Document StarIntel billing architecture, operations, and provider contracts #5

New issue

Closed

opened 2026-08-25 10:58:02 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-25 10:58:02 +00:00

(Migrated from github.com)

Goal

Create durable, operator-grade and developer-grade documentation for the starintel-biz billing subsystem so billing behavior is understandable without reading implementation code or provider dashboards.

Dependencies

#1 — canonical billing ledger and payment state machine
#2 — Stripe adapter
#3 — crypto payment adapter
#4 — entitlement and quota projection
lost-rob0t/starintel-server#125 — entitlement enforcement boundary

Required docs

Create and maintain at least:

Architecture

billing domain overview and trust boundaries
canonical entities and state machines
provider-neutral event flow
provider adapter boundary
entitlement projection boundary
webhook ingress/reconciliation flow
relationship between billing state, auth scopes, tenant policy, and effective entitlements
audit/event model and idempotency model

Stripe

API/version pinning policy
checkout/payment/subscription lifecycle mapping
webhook signature verification and replay handling
event-to-domain mapping table
test-mode workflow
reconciliation/recovery procedure
secret locations and rotation procedure without exposing secret values

Crypto

selected processor/provider rationale after #3 AUTO-RAGE research
custody boundary
invoice/quote/expiry semantics
finality/confirmation model
under/overpayment policy
reconciliation/reorg/manual-review workflow
refund/support operational notes

Entitlements

plan/product -> entitlement projection model
grace/suspension/cancellation semantics
quota behavior
revision/stale-cache semantics
StarIntel server enforcement integration

Operations/runbooks

provider outage
missed webhook/event recovery
duplicate/out-of-order event investigation
stuck invoice/payment
refund/dispute/reversal
account entitlement mismatch
reconciliation command/job usage
backup/restore and data-integrity checks
safe provider credential rotation
incident/audit evidence collection

Security/privacy

explicit data classification: what StarIntel stores vs never stores
payment-secret/PAN/private-key boundaries
webhook threat model summary
logging/redaction requirements
retention/privacy expectations
operator access model

Diagrams/examples

Include concise sequence/data-flow diagrams for:

successful purchase
recurring renewal
payment failure + recovery
Stripe webhook -> canonical state -> entitlement projection
crypto invoice -> confirmation -> entitlement projection
cancellation/refund/reversal

Documentation location

AUTO-RAGE must inspect the repo's emerging structure and choose a durable convention such as docs/ plus a concise top-level README index. Avoid creating multiple competing sources of truth. Link related implementation code/tests from docs rather than duplicating exact implementation details that will drift.

Acceptance

a new developer can explain the canonical billing authority and provider boundaries from docs alone
an operator can safely recover from a missed webhook/provider outage using the runbooks
documented state/event names match the implemented contracts/tests
secret examples use placeholders only
docs contain no real customer/payment/provider credentials or private topology
all four billing issues and server #125 are cross-referenced
docs are validated by repo-native docs/link checks where available

Execution mode — AUTO-RAGE

Run the full ADARD/ADADR loop autonomously: inspect current repo/docs conventions and implementation issues; design the smallest durable documentation information architecture; adversarial review for stale/misleading/security-sensitive documentation; autonomous decision gate; write docs alongside implementation reality; verify links/examples/commands against exact head; push a focused branch and open/update a PR targeting main. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

## Goal Create durable, operator-grade and developer-grade documentation for the `starintel-biz` billing subsystem so billing behavior is understandable without reading implementation code or provider dashboards. ## Dependencies - #1 — canonical billing ledger and payment state machine - #2 — Stripe adapter - #3 — crypto payment adapter - #4 — entitlement and quota projection - `lost-rob0t/starintel-server#125` — entitlement enforcement boundary ## Required docs Create and maintain at least: ### Architecture - billing domain overview and trust boundaries - canonical entities and state machines - provider-neutral event flow - provider adapter boundary - entitlement projection boundary - webhook ingress/reconciliation flow - relationship between billing state, auth scopes, tenant policy, and effective entitlements - audit/event model and idempotency model ### Stripe - API/version pinning policy - checkout/payment/subscription lifecycle mapping - webhook signature verification and replay handling - event-to-domain mapping table - test-mode workflow - reconciliation/recovery procedure - secret locations and rotation procedure without exposing secret values ### Crypto - selected processor/provider rationale after #3 AUTO-RAGE research - custody boundary - invoice/quote/expiry semantics - finality/confirmation model - under/overpayment policy - reconciliation/reorg/manual-review workflow - refund/support operational notes ### Entitlements - plan/product -> entitlement projection model - grace/suspension/cancellation semantics - quota behavior - revision/stale-cache semantics - StarIntel server enforcement integration ### Operations/runbooks - provider outage - missed webhook/event recovery - duplicate/out-of-order event investigation - stuck invoice/payment - refund/dispute/reversal - account entitlement mismatch - reconciliation command/job usage - backup/restore and data-integrity checks - safe provider credential rotation - incident/audit evidence collection ### Security/privacy - explicit data classification: what StarIntel stores vs never stores - payment-secret/PAN/private-key boundaries - webhook threat model summary - logging/redaction requirements - retention/privacy expectations - operator access model ### Diagrams/examples Include concise sequence/data-flow diagrams for: 1. successful purchase 2. recurring renewal 3. payment failure + recovery 4. Stripe webhook -> canonical state -> entitlement projection 5. crypto invoice -> confirmation -> entitlement projection 6. cancellation/refund/reversal ## Documentation location AUTO-RAGE must inspect the repo's emerging structure and choose a durable convention such as `docs/` plus a concise top-level README index. Avoid creating multiple competing sources of truth. Link related implementation code/tests from docs rather than duplicating exact implementation details that will drift. ## Acceptance - a new developer can explain the canonical billing authority and provider boundaries from docs alone - an operator can safely recover from a missed webhook/provider outage using the runbooks - documented state/event names match the implemented contracts/tests - secret examples use placeholders only - docs contain no real customer/payment/provider credentials or private topology - all four billing issues and server #125 are cross-referenced - docs are validated by repo-native docs/link checks where available ## Execution mode — AUTO-RAGE Run the full ADARD/ADADR loop autonomously: inspect current repo/docs conventions and implementation issues; design the smallest durable documentation information architecture; adversarial review for stale/misleading/security-sensitive documentation; autonomous decision gate; write docs alongside implementation reality; verify links/examples/commands against exact head; push a focused branch and open/update a PR targeting `main`. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.