Skip to main content

Platform Model

Understanding the relationships between Azotte's core entities is essential for successful integration and platform operation. This page explains how all the components work together.

Entity Relationship Overview​

Azotte's platform is built around a hierarchical model that enables multi-tenant, multi-storefront subscription commerce:

Core Hierarchy​

Tenant → Storefront → Bundle → Entitlement​

This represents the platform configuration hierarchy:

Tenant​

  • The top-level organizational boundary
  • Represents a business or organization using Azotte
  • Contains all configuration, storefronts, and customer data
  • Provides complete isolation between different businesses

Storefront​

  • Channel or region-specific sales environment
  • Multiple storefronts can exist within a tenant
  • Each storefront can have different:
    • Payment providers
    • Regional settings
    • Pricing models
    • Available bundles

Bundle​

  • Subscription product offering
  • Defines what customers can purchase
  • Contains pricing information
  • Available in specific storefronts
  • Groups together multiple entitlements

Entitlement​

  • Individual access rights or features
  • Granted to customers when they subscribe to a bundle
  • Examples: API rate limits, feature flags, service access
  • Building blocks of subscription offerings

Customer Journey​

Customer → Subscription → Payment​

This represents the customer lifecycle:

Customer​

  • End user who purchases subscriptions
  • Associated with a specific storefront
  • Can have multiple active subscriptions
  • Unique within a storefront context

Subscription​

  • Active service agreement
  • Links a customer to a bundle
  • Defines billing cycle and terms
  • Contains subscription state (active, paused, cancelled)
  • Generates payment obligations

Payment​

  • Financial transaction
  • Processes subscription charges
  • Handles one-time and recurring payments
  • Routes through configured payment providers
  • Maintains payment history and status

Key Relationships​

Multi-Storefront Architecture​

Tenant: "GlobalCorp"
├── Storefront: "US Store" (USD, Stripe)
│   ├── Bundle: "Pro Plan" ($29/month)
│   └── Bundle: "Enterprise" ($99/month)
├── Storefront: "EU Store" (EUR, PayPal)
│   ├── Bundle: "Pro Plan" (€25/month) 
│   └── Bundle: "Enterprise" (€85/month)
└── Storefront: "APAC Store" (JPY, Local PSP)
    ├── Bundle: "Pro Plan" (¥3,200/month)
    └── Bundle: "Enterprise" (¥9,800/month)

Entitlement Distribution​

Bundle: "Pro Plan"
├── Entitlement: "API Access" (10,000 calls/month)
├── Entitlement: "Feature: Analytics" (enabled)
├── Entitlement: "Feature: Integrations" (5 active)
└── Entitlement: "Support: Email" (business hours)

Customer Subscription Example​

Customer: "john@example.com" (US Store)
└── Subscription: "Pro Plan"
    ├── Status: Active
    ├── Billing Cycle: Monthly  
    ├── Next Payment: $29 on 2024-04-15
    └── Active Entitlements:
        ├── API Access: 10,000 calls/month
        ├── Analytics Dashboard: Enabled
        ├── Integrations: 5/5 slots used
        └── Email Support: Available

Payment Flow Integration​

How Payments Connect Everything​

  1. Customer subscribes to a Bundle in a Storefront
  2. Subscription is created linking customer and bundle
  3. Payment Provider (configured in storefront) processes charges
  4. Payments are generated based on subscription billing cycle
  5. Entitlements are activated/maintained based on payment status

Payment Provider Routing​

Storefront Configuration:
├── Primary PSP: Stripe (handles 80% of traffic)
├── Fallback PSP: PayPal (if Stripe fails)
└── Regional PSP: Local Bank (for specific payment methods)

Implementation Patterns​

1. Multi-Tenant Configuration​

// Configure tenant with multiple storefronts
const tenant = {
  id: "globalcorp",
  name: "Global Corporation",
  storefronts: [
    {
      id: "us-store",
      region: "US", 
      currency: "USD",
      paymentProviders: ["stripe", "paypal"]
    },
    {
      id: "eu-store", 
      region: "EU",
      currency: "EUR",
      paymentProviders: ["stripe", "adyen"]
    }
  ]
};

2. Bundle and Entitlement Setup​

// Create bundle with entitlements
const bundle = {
  id: "pro-plan",
  name: "Pro Plan",
  storefrontId: "us-store",
  pricing: {
    amount: 2900, // $29.00 in cents
    currency: "USD",
    interval: "month"
  },
  entitlements: [
    {
      type: "api_limit",
      value: 10000,
      unit: "calls_per_month"
    },
    {
      type: "feature_flag",
      value: "analytics_dashboard",
      enabled: true
    }
  ]
};

3. Customer Subscription Flow​

// Create subscription for customer
const subscription = {
  customerId: "cust_abc123",
  bundleId: "pro-plan", 
  storefrontId: "us-store",
  billingCycle: "monthly",
  startDate: "2024-03-15",
  paymentMethod: "pm_stripe_card_xxx"
};

Common Use Cases​

Enterprise Multi-Brand Management​

A enterprise company operating multiple brands:

Tenant: "ConglomCorp"
├── Storefront: "Brand A" 
│   ├── Bundles: Brand A specific plans
│   └── Payment Providers: Brand A merchant accounts
├── Storefront: "Brand B"
│   ├── Bundles: Brand B specific plans  
│   └── Payment Providers: Brand B merchant accounts
└── Storefront: "Brand C"
    ├── Bundles: Brand C specific plans
    └── Payment Providers: Brand C merchant accounts

Global Market Expansion​

SaaS company expanding to new regions:

Tenant: "SaaS Corp"  
├── Storefront: "North America" (USD, Stripe)
├── Storefront: "Europe" (EUR, Adyen) 
├── Storefront: "Asia Pacific" (JPY, local PSPs)
└── Storefront: "Latin America" (BRL, MercadoPago)

Each storefront can have:

  • Region-appropriate payment methods
  • Local currency pricing
  • Compliance with local regulations
  • Culturally adapted bundle offerings

Data Flow Summary​

  1. Configuration Flow: Tenant → Storefront → Bundle → Entitlement
  2. Customer Flow: Customer → Subscription → Bundle → Entitlements
  3. Payment Flow: Subscription → Payment → Payment Provider → Settlement
  4. Entitlement Flow: Payment Success → Entitlement Activation → Customer Access

This model enables Azotte to handle complex, multi-region, multi-brand subscription businesses while maintaining clear separation and flexibility for different market requirements.