Subscription and License Management

In on-premise deployments, Cognipeer uses a license-based subscription system instead of traditional payment-based subscriptions. This provides a seamless experience where workspace limits, features, and credits are automatically configured through your license file.

Overview

On-premise subscription management differs from SaaS in several key ways:

Feature	SaaS Mode	On-Premise Mode
Plan Selection	Manual during onboarding	Automatic from license
Payment	Stripe integration	No payment required
Plan Changes	Self-service via UI	Contact administrator
Credits	Monthly billing cycle	License-defined allocation
Limits	Plan-based via Stripe	License configuration

How It Works

1. License-Based Configuration

Your on-premise license file defines:

• Plan Type: free, standard, pro, or custom
• Monthly Credits: Allocated credits for AI operations
• Workspace Limits:
  • Number of peers (AI agents)
  • Datasources
  • Custom tools
  • Team members (users)
  • Datasource usage limits
  • Tool call limits
  • Version retention periods

2. Automatic Application

When a workspace is created:

1. System reads license configuration
2. Identifies the plan type (from config.licenseConfig.plan)
3. Applies corresponding limits and credits
4. Sets subscription status to "active"
5. No user intervention required

3. No Payment Processing

On-premise deployments:

• ✅ Skip subscription selection during onboarding
• ✅ No Stripe integration needed
• ✅ No credit card or billing information required
• ✅ No checkout sessions or payment webhooks

Configuration

License File Structure

Your license file (typically in environment configuration) includes:

{
  "plan": "pro",                    // Plan level: free, standard, pro, enterprise
  "limits": {
    "peers": 50,                    // Maximum AI peers
    "datasources": 20,              // Maximum datasources
    "tools": 100,                   // Maximum custom tools
    "users": 25,                    // Maximum team members
    "datasourceUsage": 1000000,     // Datasource usage limit
    "customTools": 50,              // Custom tool limit
    "datasourceSyncInterval": 60,   // Sync interval in minutes
    "maxToolCallsPerConversation": 50,
    "toolCallProfiles": true,       // Enable tool call profiling
    "versionRetention": {
      "app": 10,                    // Keep last 10 app versions
      "peer": 10                    // Keep last 10 peer versions
    }
  },
  "credits": {
    "monthly": 100000               // Monthly credit allocation
  }
}

Plan Defaults

If not specified in license, default plans are:

Free Plan

{
  "peers": 3,
  "datasources": 2,
  "tools": 10,
  "users": 1,
  "monthlyCredit": 1000
}

Standard Plan

{
  "peers": 10,
  "datasources": 5,
  "tools": 30,
  "users": 5,
  "monthlyCredit": 10000
}

Pro Plan

{
  "peers": 50,
  "datasources": 20,
  "tools": 100,
  "users": 25,
  "monthlyCredit": 100000
}

User Experience

During Onboarding

On-Premise Flow:

1. User creates account
2. Subscription page is automatically skipped
3. System applies license-based plan
4. User proceeds directly to onboarding
5. Workspace created with license limits

SaaS Flow:

1. User creates account
2. User selects subscription plan
3. Payment information collected
4. Workspace created with selected plan

In Settings

On-Premise Subscription Page:

Users will see a read-only view showing:

ℹ️ Your subscription plan is managed via your license.
   Contact your administrator for plan changes.

Current Plan: Pro Plan
Status: Active
Managed By: License

Plan Features:
✓ 50 AI Peers
✓ 20 Datasources
✓ 100 Custom Tools
✓ 25 Team Members
✓ 100,000 Monthly Credits

No Editable Options:

• No "Upgrade Plan" button
• No payment method section
• No billing history
• No cancellation option

SaaS Subscription Page:

Shows full subscription management:

• Current plan with upgrade/downgrade options
• Payment method management
• Billing history
• Usage statistics
• Plan change buttons

Backend Implementation

Subscription Service

The subscription service (services/subscription.js) automatically detects on-premise mode:

getPlans()

// On-prem: Returns empty array (no selectable plans)
// SaaS: Returns available subscription plans

getStatus()

// On-prem: Returns license-based info
{
  planKey: "pro",
  status: "active",
  isLicenseBased: true,
  features: { ... },
  limits: { ... },
  monthlyCredit: 100000
}

// SaaS: Returns Stripe subscription info
{
  planKey: "pro",
  status: "active",
  customerId: "cus_xxx",
  subscriptionId: "sub_xxx",
  currentPeriodEnd: "2024-02-01"
}

activateFree()

// On-prem: Returns success without action
// SaaS: Activates free plan via Stripe

createCheckoutSession()

// On-prem: Throws error - not available
// SaaS: Creates Stripe checkout session

Workspace Service

The workspace service applies license configuration:

// services/workspace.js
async function applyLicensePlan(workspace) {
  const plan = config.licenseConfig.plan || 'free';
  const limits = config.licenseConfig.limits || getDefaultLimits(plan);
  const credits = config.licenseConfig.credits || getDefaultCredits(plan);
  
  workspace.limits = limits;
  workspace.monthlyCredit = credits.monthly;
  workspace.monthlyCreditUsed = 0;
  workspace.subscription = {
    planKey: plan,
    status: 'active',
    isLicenseBased: true
  };
  
  return workspace;
}

Called automatically during:

• New workspace creation (create())
• Local workspace setup (createLocal())

Config Endpoint

The config endpoint includes on-premise detection:

// GET /api/v1/config
{
  "mode": "onprem",
  "isOnPrem": true,
  "multiWorkspace": true,
  "signup": true,
  "googleLogin": false
}

Frontend uses isOnPrem flag to:

• Skip subscription selection during onboarding
• Show read-only subscription info in settings
• Hide payment-related UI elements

Frontend Implementation

Welcome Flow

// pages/welcome/subscription.js

useEffect(() => {
  const checkConfig = async () => {
    const config = await fetchConfig();
    
    if (config.isOnPrem) {
      // Skip subscription page
      sessionStorage.setItem('skipSubscription', 'true');
      router.push('/welcome/onboarding');
    }
  };
  
  checkConfig();
}, []);

Settings Page

// pages/settings/subscription/index.js

const SubscriptionSettings = () => {
  const config = useConfig();
  const subscription = useSubscription();
  
  if (config.isOnPrem) {
    return (
      <OnPremiseView 
        plan={subscription.planKey}
        limits={subscription.limits}
        credits={subscription.monthlyCredit}
      />
    );
  }
  
  return (
    <SaaSView 
      subscription={subscription}
      onUpgrade={handleUpgrade}
      onManagePayment={handlePayment}
    />
  );
};

Changing Plans

In On-Premise Deployments

Plan changes require administrator action:

1. Update License File

   • Modify plan level in license configuration
   • Update limits and credit allocation
   • Restart application to apply changes

2. Contact Support

   • Users contact system administrator
   • Administrator updates license
   • Changes apply to all workspaces

Communicating to Users

Display clear messaging in the UI:

{
  isOnPrem && (
    <Alert severity="info">
      Your subscription plan is managed via your license.
      Contact your administrator for plan changes or upgrades.
    </Alert>
  )
}

Credit Management

Credit Allocation

On-premise credits work the same as SaaS:

• Defined in license configuration
• Reset monthly (or per license period)
• Tracked per workspace
• Consumed by AI operations

Credit Usage

// services/workspace.js

async function consumeCredit(workspaceId, amount) {
  const workspace = await Workspace.findById(workspaceId);
  
  if (workspace.monthlyCreditUsed + amount > workspace.monthlyCredit) {
    throw new Error('Insufficient credits');
  }
  
  workspace.monthlyCreditUsed += amount;
  await workspace.save();
}

Monitoring Usage

Users can view credit usage in dashboard:

• Current month usage
• Remaining credits
• Usage trends
• No payment required for overages (contact admin)

Best Practices

For Administrators

1. Plan Appropriately

   • Set realistic limits based on organization size
   • Allocate sufficient credits for expected usage
   • Monitor usage patterns

2. Document Configuration

   • Keep license configuration documented
   • Share plan details with users
   • Provide upgrade process documentation

3. Monitor Resources

   • Track credit consumption
   • Monitor workspace limit usage
   • Plan for growth

4. Communicate Changes

   • Notify users before plan changes
   • Document new limits and features
   • Provide transition period if reducing limits

For Users

1. Understand Your Plan

   • Know your workspace limits
   • Monitor credit usage
   • Plan features accordingly

2. Request Upgrades Early

   • Don't wait until limits are reached
   • Provide usage justification
   • Allow time for administrator processing

3. Optimize Usage

   • Use credits efficiently
   • Archive unused peers/datasources
   • Follow best practices for AI operations

Troubleshooting

Issue: Limits Not Applied

Problem: Workspace limits don't match license configuration.

Solution:

1. Verify license file is correct
2. Restart application to reload config
3. Check workspace subscription status
4. Re-create workspace if needed

Issue: Credits Not Resetting

Problem: Monthly credits don't reset.

Solution:

1. Check license credit configuration
2. Verify monthly reset job is running
3. Manually reset via admin tools if needed

Issue: Users See Payment Options

Problem: Payment UI appears in on-premise deployment.

Solution:

1. Verify isOnPrem flag in config endpoint
2. Clear browser cache
3. Check frontend build includes on-premise handling

Migration Scenarios

From SaaS to On-Premise

When migrating from SaaS:

1. Export Data: Export workspaces, peers, and configurations
2. Set Up License: Configure on-premise license
3. Import Data: Import into on-premise instance
4. Update Subscription: Convert to license-based
5. Notify Users: Inform about new subscription model

From On-Premise to SaaS

When migrating to SaaS:

1. Choose Plan: Select appropriate SaaS plan
2. Export Data: Export from on-premise
3. Set Up Billing: Configure payment method
4. Import Data: Import into SaaS instance
5. Activate Subscription: Start billing cycle

See Also

• Installation Guide - Set up on-premise deployment
• Settings Overview - Managing settings
• User Management - Managing team members