Org Subscription Bootstrap & Ownership Picker

When a Malet Owner creates a new Organization, the platform automatically provisions previously provisioned a free Starter tier subscription for that Organization. This ensured tier enforcement always resolved to a valid record.

The OwnershipPicker component gives Malet Owners explicit control over which context (Personal or Organization) a new Malet is created under. This replaces the previous implicit behavior where the wizard silently inherited the global org context.

Architecture: Bootstrap Flow

sequenceDiagram
    participant UI as Frontend
    participant Orgs as organizations subgraph
    participant Pay as payments subgraph
    participant DB as MongoDB

    UI->>Orgs: createOrganization(input)
    Orgs->>DB: Save Organization document
    Orgs->>Orgs: Create Owner Membership
    Orgs->>Pay: emit('bootstrap_org_subscription', {orgId, userId})
    Pay->>DB: Upsert BillingSubscription(orgId, planId='starter', status=ACTIVE)
    Note over Pay: Idempotent — skips if active subscription exists

Event Payload

// Emitted by organizations subgraph
this.paymentsClient.emit('bootstrap_org_subscription', {
  orgId: org.id,      // Organization document ID
  userId: actor.id,   // Creator's user ID (for audit)
});

Handler: `subscription-tcp.controller.ts`

The payments subgraph listens for the bootstrap_org_subscription event and creates a free Starter subscription:

@EventPattern('bootstrap_org_subscription')
async handleBootstrapOrgSubscription(
  @Payload() data: { orgId: string; userId: string },
) {
  // Check for existing active subscription (idempotent)
  const existing = await this.subscriptionModel.findOne({
    orgId: data.orgId,
    status: 'ACTIVE',
  });
  if (existing) return; // Already bootstrapped

  // Create synthetic free subscription
  await this.subscriptionModel.create({
    orgId: data.orgId,
    userId: data.userId,
    planId: 'starter',
    status: 'ACTIVE',
    stripeSubscriptionId: `free_org_${data.orgId}`,
  });
}

Key design decisions:

• Fire-and-forget: The emit() pattern means org creation succeeds even if the payments service is temporarily unavailable
• Idempotent: Duplicate events are safely ignored
• Synthetic Stripe ID: Free plans use free_org_{orgId} — no Stripe object is created

Tier Enforcement Pipeline

When a Malet is created under an org, the resolver calls get_active_tier via TCP:

malets subgraph → TCP → payments subgraph
                         → findOne({ orgId, status: ACTIVE })
                         → returns { tier, limits }

The checkTierLimit() function in @app/common now accepts optional org context:

export function checkTierLimit(
  tier: string,
  resource: string,
  currentCount: number,
  context?: { orgName?: string },
) {
  const limits = getTierLimits(tier);
  const limit = limits[resource];
  if (currentCount >= limit) {
    const owner = context?.orgName
      ? `Your organization "${context.orgName}"`
      : "You've";
    throw new ForbiddenException(
      `${owner} reached the ${tier} plan limit of ${limit} ${resource}.`
    );
  }
}

OwnershipPicker Component

File: src/lib/components/create-malet/OwnershipPicker.svelte

A GitHub-inspired dropdown that sits above the wizard progress bar, allowing the Malet Owner to explicitly choose ownership context before creating a Malet.

Features

• Shows Personal Account with the user's display name
• Lists all Organization memberships from orgsStore with role and category metadata
• "Create new organization" link → /orgs/create?then=/create-malet
• Selected option is indicated with a check badge
• Selecting an org sets both wizard-scoped ownership AND global org context (so the GraphQL client sends x-org-id)

Wizard State: `createMaletStore.svelte.ts`

The store was updated with wizard-scoped ownership fields:

// Wizard-scoped override (set by OwnershipPicker)
wizardOrgId = $state<string | null>(null);
wizardOrgName = $state<string | null>(null);
ownershipChosen = $state(false);

// Priority chain: wizard-scoped → localStorage global context
get orgId(): string | null {
  if (this.wizardOrgId !== null) return this.wizardOrgId;
  return localStorage.getItem('currentOrgId');
}

get orgName(): string | null {
  if (this.wizardOrgName) return this.wizardOrgName;
  return localStorage.getItem('currentOrgName') || 'Your Organization';
}

setWizardOwnership(orgId: string | null, orgName: string | null) {
  this.wizardOrgId = orgId;
  this.wizardOrgName = orgName;
  this.ownershipChosen = true;
  // Persist to localStorage for cross-tab consistency
  if (orgName) localStorage.setItem('currentOrgName', orgName);
}

URL Seeding

The wizard supports ?orgId=xxx URL parameters for post-org-creation redirects:

/create-malet?orgId=abc123&tier=pro

This automatically seeds wizardOrgId from the URL and resolves the org name from localStorage cache.

OrgName Persistence

Organization names are cached in localStorage (not sessionStorage) for cross-tab persistence:

Deck Dashboard: Ownership Badges

File: ngwenya-deck/src/routes/dashboard/+page.svelte

The Deck now renders ownership badges on each Malet card:

The GET_MY_OWNED_MALETS query now includes ownerType and ownerId fields. The "Create New Malet" add-card dynamically shows "Create Malet for {orgName}" when in org context.

File Reference

Related

• Subscription Checkout Identity & Idempotency — How orgId flows through checkout, idempotency guards, and debug tracing
• Organization Context & Tier Access — How the Org Context Switcher works, canCreateOrganization() gate, and x-org-id header injection
• Subscription & Billing Architecture — Backend tier enforcement via TCP microservice and TIER_LIMITS config
• Organization & Malet Management — Frontend management UI: org dashboard, activity feed, billing
• Organizations Subgraph — Internals of the organizations subgraph including membership, invitations, and audit
• Malet-First Ownership Architecture — Payment-first provisioning ensuring Organizations and Malets are created atomically after checkout (replaces bootstrap flow)