Platform Operations

Platform-level operations for managing the multi-tenant SCP system.

Overview

Platform Operations encompasses all actions that platform staff and AI agents perform to manage the SCP platform:

• Multi-tenancy management
• Merchant and MerchantOrg onboarding
• Plugin configuration (payment, SMS, email integrations)
• User and role management (RBAC)
• Sales pipeline for potential customers
• Platform billing and subscriptions
• Financial ledger and double-entry bookkeeping
• System-wide audit logs
• Platform-level analytics

---

Contexts

Context	Purpose	Platform Actions
TenantContext	Multi-tenant configuration	Manage tenant settings, feature flags
UserContext	Platform staff authentication	Create users, manage profiles, authentication
RoleContext	Role-based access control	Define roles, assign permissions
MerchantOrgContext	B2B holding companies	Onboard merchant organizations
MerchantContext	Individual businesses	Onboard merchants, configure settings
ProspectContext	Sales pipeline	Track potential customers, manage leads
PluginContext	System integrations	Configure payment processors, SMS, email providers
SubscriptionContext	Platform billing	Manage merchant subscriptions, invoicing
TransactionContext	Financial ledger	View all transactions, reconcile accounts
TransactionJournalContext	Double-entry bookkeeping	Audit financial integrity (LHS = RHS)
AuditContext	Audit logs	View system-wide activity logs

---

Key Features

Multi-Tenancy Management

• Configure tenant settings and feature flags
• Manage tenant-level plugins (platform-wide integrations)
• Set up tenant billing and payment accounts
• Monitor tenant resource usage

Merchant Onboarding

• Create MerchantOrgs (B2B holding companies)
• Onboard individual Merchants under MerchantOrgs
• Configure merchant-specific plugins (no inheritance from tenant)
• Set up merchant payment processing
• Assign merchant-level feature flags

Plugin Management

• Configure platform-level plugins (Tenant ↔ MerchantOrg interactions)
• Set up payment processors (Stripe, Square, Adyen)
• Configure SMS providers (Twilio, AWS SNS)
• Set up email providers (Mailgun, SendGrid)
• Manage plugin credentials and API keys

User & Role Management (RBAC)

• Create platform staff user accounts
• Define custom roles with granular permissions
• Assign roles to users
• Impersonate merchant staff for support
• Manage user authentication and sessions

Sales Pipeline

• Track prospects (potential merchant customers)
• Manage sales stages (lead → qualified → closed)
• Record sales activities and notes
• Convert prospects to merchants

Platform Billing

• Create subscription plans (monthly, annual)
• Manage merchant subscriptions
• Generate invoices for merchants
• Process subscription payments
• Handle subscription upgrades/downgrades
• Track MRR (Monthly Recurring Revenue)

Financial Ledger

• View all transactions across all merchants
• Track revenue flows (EndCustomer → Merchant → MerchantOrg → Tenant)
• Reconcile accounts using double-entry bookkeeping
• Ensure financial integrity (LHS = RHS via TransactionJournal)
• Export financial data for accounting

System-Wide Audit Logs

• View all actions across all merchants
• Filter by actor type (end_customer, staff, ai_agent, system)
• Search by resource type (appointment, payment, refund)
• Export audit trails for compliance
• Monitor for suspicious activity

Platform Analytics

• Track platform-wide metrics (total revenue, bookings, merchants)
• Monitor merchant health and activity
• Identify churn risks
• View growth trends
• Export data for business intelligence

---

AI Agent Capabilities

AI agents can assist with platform operations:

Merchant Support

• Answer merchant questions about SCP features
• Help merchants configure settings
• Troubleshoot issues with bookings or payments
• Guide merchants through onboarding

Proactive Monitoring

• Detect merchant churn risks
• Alert on unusual payment patterns
• Monitor system health and performance
• Flag compliance issues

Automated Tasks

• Send onboarding emails to new merchants
• Process subscription renewals
• Generate monthly usage reports
• Archive inactive merchants

---

Tenant → MerchantOrg → Merchant Hierarchy

Tenant (Platform Operator)
  ├─> Tenant Plugins (platform-level integrations)
  ├─> Users (platform staff with roles)
  └─> MerchantOrgs (B2B holding companies)
       └─> Merchants (individual businesses)
            ├─> Merchant Plugins (merchant-specific, no inheritance)
            ├─> Providers, Locations, Services
            └─> EndCustomers
                 └─> Appointments, Payments

Key Principles:

• Tenant Plugins: For Tenant ↔ MerchantOrg interactions (platform billing)
• Merchant Plugins: For Merchant ↔ EndCustomer interactions (service payments)
• No Plugin Inheritance: Merchants configure their own plugins independently

---

Flow of Funds

EndCustomers → Merchants → MerchantOrgs → Tenant

From	To	Purpose	Context
EndCustomers	Merchants	Pay for services	PaymentContext, InvoiceContext
Merchants	MerchantOrgs	Franchise fees, commissions	TransactionContext
MerchantOrgs	Tenant	Platform subscription fees	SubscriptionContext

---

Related Capabilities

• EndCustomer Self-Serve - Customer-facing capabilities
• Merchant Operations - Merchant staff capabilities
• Platform Finance - Platform billing details

Related API Endpoints

See the API Reference for platform operations endpoints:

• GET /api/tenants - Tenant configuration
• GET /api/merchant-orgs - Merchant organizations
• GET /api/merchants - Merchant management
• GET /api/users - User management
• GET /api/roles - Role management
• GET /api/audit-logs - Audit logs