Platform Management
Concurrency-safe quota counters with pooled enforcement, trial resource snapshots, and the non-Connect commission ledger for PayPal and Paymob gateway commissions.
Platform Management covers the operational infrastructure that keeps SCRIPE's multi-tenant platform numerically consistent: quota counters that prevent resource over-provisioning, trial snapshots that enable accurate downgrade enforcement, and the commission ledger that tracks platform revenue from non-Stripe-Connect payment gateways.
What Is Platform Management?
Platform Management is the collection of domain entities responsible for enforcing tenant resource limits (quotas), capturing resource state at trial start, and tracking platform commissions from PayPal and Paymob gateway payments. These components work together to ensure billing integrity and fair resource allocation across the multi-tenant hierarchy.
QuotaCounter Entity
QuotaCounter tracks resource usage per tenant with optional pooled enforcement. One row exists per tenant per resource type (admin, role, subtenant, usergroup). The reservation pattern prevents race conditions under concurrent creation requests.
| Field | Type | Description |
|---|---|---|
| TenantId | Guid | The tenant this counter belongs to. |
| ResourceType | string (max 50) | Resource being tracked: "admin", "role", "subtenant", "usergroup". |
| Used | int | Number of confirmed resources (actual count after commit). |
| Reserved | int | Number of in-flight reservations (being created but not yet committed). |
| Max | int | Maximum allowed for this tenant. -1 = unlimited. |
| PoolRootTenantId | Guid? | Links to the root tenant of a pooled quota. Null = no pooling (per-tenant limit only). When set, the SUM of (Used + Reserved) across all counters sharing this root must not exceed PoolMax. |
| PoolMax | int | Maximum for the entire pool. Only meaningful on the root counter row. -1 = unlimited. |
Atomic Reservation Pattern
The reservation pattern is a three-phase protocol that prevents quota over-provisioning even under high concurrency.
Quota Enforcement Modes
QuotaCounter supports two enforcement modes controlled by PoolRootTenantId. Per-tenant enforcement is the default; pooled enforcement enables resource sharing across a tenant hierarchy (e.g. a parent tenant that allocates admins across its sub-tenants).
| Mode | Enforcement |
|---|---|
| Per-Tenant (PoolRootTenantId = null) | Each tenant is enforced independently: (Used + Reserved) < Max. |
| Pooled (PoolRootTenantId set) | SUM(Used + Reserved) across all rows sharing the same PoolRootTenantId must not exceed PoolMax (stored on the root's counter row). |
TrialSnapshot Entity
A TrialSnapshot captures the resource counts (admin, role, sub-tenant, user-group) at the exact moment a trial subscription begins. At trial expiry, the system compares current counts against the snapshot to determine if the tenant provisioned resources beyond the base edition's limits during the trial period.
| Field | Type | Description |
|---|---|---|
| SubscriptionId | Guid | FK to the TenantSubscription this snapshot belongs to. |
| TenantId | Guid | The tenant this snapshot is for. |
| AdminCount | int | Number of admins at trial start. |
| RoleCount | int | Number of roles at trial start. |
| SubTenantCount | int | Number of sub-tenants at trial start. |
| UserGroupCount | int | Number of user groups at trial start. |
| CapturedAt | DateTime | UTC timestamp when the snapshot was captured. |
CommissionLedgerEntry Entity
CommissionLedgerEntry records commissions from non-Connect gateway payments (PayPal, Paymob). For Stripe Connect payments, commissions are collected instantly via application_fee_amount — this entity is only for post-billing gateway flows that require deferred commission collection.
| Field | Type | Description |
|---|---|---|
| TenantId | Guid | The tenant whose user made the payment. |
| UserSubscriptionId | Guid | The UserSubscription that generated this commission. |
| PaymentTransactionId | Guid? | FK to the PaymentTransaction for this user payment. |
| CommissionInvoiceId | Guid? | FK to CommissionInvoice once invoiced. Null while Unbilled. |
| Gateway | PaymentGatewayType | Which gateway processed the payment (PayPal or Paymob). Not used for Stripe Connect — those use application_fee_amount directly. |
| GatewayTransactionId | string (max 255) | Gateway-specific transaction ID for reconciliation and deduplication. |
| GrossAmount | decimal (18,2) | Full amount paid by the user (arrived in the tenant's account). |
| CommissionRate | decimal (5,4) | Commission rate applied at the time of payment (e.g. 0.10 = 10%). |
| CommissionAmount | decimal (18,2) | Platform commission = GrossAmount × CommissionRate. |
| Currency | Currency enum | ISO 4217 currency code. Should match the tenant's billing currency. |
| Status | CommissionLedgerStatus | Lifecycle: Unbilled → Invoiced → Paid / Waived / WriteOff. |
| Notes | string? (max 1000) | Admin notes — used when waiving or writing off a commission. |
Revenue Analytics Integration
The commission ledger feeds directly into the Revenue Analytics module for platform-wide financial reporting.
| Metric | Source |
|---|---|
| Total commission collected | SUM(CommissionLedgerEntry.CommissionAmount) WHERE Status = Paid |
| Unbilled commission exposure | SUM(CommissionLedgerEntry.CommissionAmount) WHERE Status = Unbilled |
| Tenant payout totals | TenantStripeAccount.TotalPayoutsAmount |
| Trial resource usage | TrialSnapshot compared to current QuotaCounter.Used at expiry |
API Endpoints
Platform management endpoints are restricted to super-admin roles. Quota data is read-only for standard platform admins.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/platform/quotas | List all quota counters (filterable by tenant, resource type) | 🔒 Required |
| GET | /api/v1/platform/quotas/{tenantId}/{resourceType} | Get the quota counter for a specific tenant and resource type | 🔒 Required |
| POST | /api/v1/platform/quotas/reset | Reset a quota counter to zero or a specified baseline | 🔒 Required |
| GET | /api/v1/platform/trial-snapshots/{subscriptionId} | Get the trial resource snapshot captured at trial start | 🔒 Required |
| GET | /api/v1/platform/commission-ledger | List commission ledger entries (filterable by tenant, gateway, status) | 🔒 Required |
| PUT | /api/v1/platform/commission-ledger/{id}/waive | Waive a commission ledger entry with an admin note | 🔒 Required |
| GET | /api/v1/platform/dashboard | Get platform management dashboard summary metrics | 🔒 Required |