Skip to documentation
OrbitMeshDocs
Browse documentation
Docs/Platform Systems

PLATFORM SYSTEMS

Billing And Tenant Plans

Billing in OrbitMesh is centered on the tenant.
View source

1. Positioning

Billing in OrbitMesh is centered on the tenant.

The first commercial model is:

Tenant Plan Subscription

It means a tenant is subscribed to a plan. The plan controls the tenant's resource pool, enabled capabilities, traffic allowance, operational features, and account-system limits.

This must not be confused with:

Client Access Subscription

Client Access Subscription is the user-facing Traffic subscription link used by Clash, Surge, Shadowrocket, sing-box, and similar clients.

2. Naming

Use these terms consistently:

Plan
  Package definition, such as Free, Pro, Team, Enterprise.

Plan Version
  Immutable version of a Plan's entitlement and quota definition.

Tenant Plan Subscription
  A tenant's active, trialing, expired, or canceled subscription to a Plan Version.

Entitlement
  A functional or resource permission granted by a Plan Version.

Plan Quota Template
  A quota rule template granted by a Plan Version.

Client Access Subscription
  A user-owned client configuration and protocol credential entry.

Do not use a generic subscription name for tenant billing. Use tenant_plan_subscription when the subject is billing, and client_access_subscription when the subject is client access.

3. Product Principles

OrbitMesh should not be designed as an unlimited traffic resale panel.

Early billing should prioritize:

  • SaaS Control Plane.
  • Node management.
  • Traffic policy engine.
  • Usage and quota management.
  • Observability.
  • Team and account management.
  • Managed Node.
  • Enterprise deployment.

Platform-borne traffic allowance can be part of the plan, but it is not the only value. BYOH traffic should be measured for observability and tenant governance, not treated as platform-borne traffic by default.

4. Tenant-Level Scope

Tenant Plan applies to the whole tenant:

Account
  -> Tenant
    -> Users
    -> Nodes
    -> Runtime Bindings
    -> Traffic Endpoints
    -> Client Access Subscriptions

Users do not need individual plans in the MVP. A user who joins nodes or creates client access subscriptions consumes the tenant's plan limits.

Example:

Tenant Plan:
  max_nodes = 5
  included_platform_traffic = 500 GB/month
  optional tenant governance quota = 500 GB/month

User A:
  owns 1 BYOH node
  owns 2 client access subscriptions

Result:
  tenant node usage increases by 1
  tenant client access subscription usage increases by 2
  BYOH traffic from User A is measured and can count toward tenant governance
  quota, but it is not platform-borne billable traffic unless it uses managed
  nodes, platform relay, platform egress, or another platform-owned data-plane
  resource

5. Account System Alignment

Billing introduces an account-system boundary:

Account
  Billing and ownership subject.

Tenant
  Product workspace and resource container.

User
  Login identity.

Tenant Membership
  User's role inside a tenant.

MVP may keep the current tenant/user model, but the plan design must leave room for:

  • account owner.
  • billing role.
  • multiple tenants under one account.
  • service accounts.
  • RBAC.
  • audit logs.
  • SSO/OIDC/LDAP.

6. Plan Dimensions

Tenant Plan dimensions are grouped into:

  • plan metadata.
  • tenant subscription lifecycle.
  • account and membership limits.
  • node access limits.
  • Traffic limits.
  • Capability permissions.
  • domain, TLS, Gateway, and Tunnel limits.
  • observability, operations, and security limits.

Traffic dimensions must distinguish:

  • BYOH traffic: user-owned infrastructure cost; default is unlimited from platform billing perspective, but tenant admins may apply governance quota.
  • Managed Node traffic: platform-owned infrastructure cost; eligible for plan allowance and billing.
  • Platform Relay traffic: platform-owned relay cost; eligible for plan allowance and billing.
  • Platform Egress traffic: platform-owned exit cost; eligible for plan allowance and billing.

Plan can include future expansion abilities, but every entitlement key must have a maturity:

implemented
  Current code can enforce or display it.

planned
  Product direction is accepted, but it is not an available tenant capability yet.

reserved
  Namespace reservation only.

Only implemented entitlements may affect API validation, quota synchronization, compiler output, or Console capability display.

The detailed implementation model is defined in:

7. Relationship With Quota

Plan is not the same as quota policy.

Plan grants quota templates:

Plan Version
  -> Plan Quota Template
    -> effective tenant quota

For the MVP, the simplest implementation is:

Tenant Plan Subscription
  -> sync plan quota templates into quota_policies
  -> quota_enforcements evaluate usage

Longer term, OrbitMesh should use an Effective Entitlement Engine:

effective entitlement
  = plan entitlements
  + plan quota templates
  + addons
  + manual overrides
  + enterprise contract overrides

8. MVP Scope

MVP should implement:

  • plan catalog seed data. Implemented for Free and Pro.
  • plan versions. Implemented.
  • tenant plan subscription. Implemented in Control Plane schema and Platform API.
  • entitlement key/value model. Implemented.
  • plan quota templates. Implemented.
  • tenant monthly client_access total traffic quota.
  • tenant limits for nodes, members, client access subscriptions, runtime bindings, and core capabilities.
  • Tenant Console Settings / Plan & Billing read-only/current-state page.
  • Platform Console plan administration under apps/platform.

Implemented Platform API namespace:

GET  /api/v1/platform/plans
GET  /api/v1/platform/tenants/{tenant_id}/plan-subscription
PUT  /api/v1/platform/tenants/{tenant_id}/plan-subscription
GET  /api/v1/platform/tenants/{tenant_id}/effective-entitlements
POST /api/v1/platform/tenants/{tenant_id}/plan-subscription/sync-quota

MVP does not require:

  • payment provider integration.
  • invoices.
  • tax calculation.
  • seat billing.
  • user-level purchased plans.
  • addon marketplace.

9. Acceptance

Tenant Plan MVP is acceptable when:

  • every tenant has one active or trialing tenant plan subscription.
  • Console shows current plan, period, enabled capabilities, limits, and usage.
  • plan quota templates can produce effective tenant traffic quota.
  • node enrollment respects max_nodes.
  • client access subscription creation respects max_client_access_subscriptions.
  • capability creation respects plan capability entitlements.
  • expired or suspended tenant plans block new resource creation.

10. Console Boundary

apps/console is the Tenant Console. It may show:

  • current tenant plan.
  • current period and expiry.
  • tenant usage and quota state.
  • plan-derived quota state.
  • BYOH governance quota state.

apps/console must not implement platform operator workflows.

apps/platform is the Platform Console. It owns:

  • plan catalog, plan versions, and plan terms.
  • price, currency, duration, trial, and visibility configuration.
  • tenant plan assignment, upgrade, downgrade, suspension, and expiry.
  • managed node, platform relay, and platform egress resource pools.
  • platform-borne traffic allowance and cost analytics.
  • system-level runtime catalog, subscription target catalog, domain, DNS, ACME, and certificate administration.
OrbitMesh DocumentationContent follows the repository's main branch.