classroomio/prd/multi-workspace/README.md

---
name: Multi-Workspace (Multiple Orgs Under One Account)
overview: Allow a single customer account to operate multiple organizations ("workspaces") under one subscription. The customer pays in their primary workspace; secondary workspaces inherit the subscription, share pooled quotas (learners, AI tokens), and don't bill separately. Surfaces as a paid tier feature — Growth includes 2 workspaces, Business 3, Enterprise unlimited; extras as a paid add-on. Wedge story: "one account, multiple academies" — customer-facing + internal + partners under one bill.
todos:
  - id: schema-decision
    content: Decide between Option A (parentOrganizationId on organization) and Option B (separate account table). Recommendation: Option A for v1.
    status: pending
  - id: data-model
    content: Add parentOrganizationId column to organization table; backfill existing orgs to NULL (primary)
    status: pending
  - id: billing-routing
    content: Refactor Stripe subscription handling so the primary workspace holds the subscription and webhook events propagate state to all linked workspaces
    status: pending
  - id: pooled-quotas
    content: Move learner-count and AI-token quota enforcement from per-org to per-account (sum across linked workspaces)
    status: pending
  - id: account-endpoints
    content: Build POST/GET/DELETE /account/workspaces and GET /account/usage endpoints
    status: pending
  - id: account-settings-ui
    content: Build account settings page accessible from primary workspace — list workspaces, per-workspace usage, "Create workspace" CTA
    status: pending
  - id: workspace-switcher
    content: Update existing org switcher to clearly distinguish "workspaces in my account" vs "orgs I'm invited to"
    status: pending
  - id: secondary-billing-ui
    content: Hide or alias billing UI in secondary workspaces — show "Billing managed by [primary workspace name]"
    status: pending
  - id: downgrade-grace
    content: Implement 7-day read-only grace period when a customer downgrades below their current workspace count
    status: pending
  - id: free-tier-cap
    content: Enforce 1-workspace cap on Free tier to prevent abuse
    status: pending
  - id: pricing-page-update
    content: Update marketing pricing page to surface "Workspaces included" row and add-on pricing
    status: pending
  - id: homepage-section
    content: Add "One account, multiple academies" section to apps/website homepage (after feature ships)
    status: pending
isProject: true
---

# Multi-Workspace PRD

## Status

- Draft (2026-05-15)
- Owner: TBD

## Problem

Today, every ClassroomIO organization is its own billing entity. A customer who wants:
- A customer-facing academy on `learn.acme.com`, AND
- An internal employee training portal on `team.acme.com`

…must create two separate orgs with two separate paid subscriptions. This:
1. Doubles the cost for no clear product reason
2. Creates billing friction (two invoices, two payment methods)
3. Discourages expansion
4. Misses the wedge story — "one account, multiple academies"

## Goals

1. Let a customer create multiple workspaces (full orgs) under a single subscription
2. Enable centralized billing — one Stripe customer, one invoice
3. Share quotas (learners, AI tokens) across linked workspaces
4. Surface this as a paid tier feature: Growth includes 2 workspaces, Business 3, Enterprise unlimited; extras as paid add-on
5. Keep each workspace fully independent operationally (own brand, domain, members, courses, certificates)

## Non-goals (v1)

- Cross-workspace data sharing (a learner enrolling in courses across both workspaces with a single identity)
- Cross-workspace analytics roll-ups
- Reparenting a workspace to a different primary mid-subscription (manual support op for v1)
- Self-serve "split off" of a secondary workspace into its own subscription (manual for v1)
- Per-workspace seat limits separate from pooled quota

## Users & jobs

| Persona | Job |
|---|---|
| **Account owner** (founder / VP CX) | "I want a second academy for our internal team without paying for a second plan." |
| **Workspace admin** (delegated owner of a secondary workspace) | "I want to manage my workspace fully — branding, courses, members — without seeing billing." |
| **Learner** | No change. Sees only their workspace. |

## Key concepts

- **Account** — the billing entity. Tied to one Stripe customer. Owns 1+ workspaces.
- **Workspace** — a full `organization` row (custom domain, branding, members, courses). Each workspace has exactly one parent account.
- **Primary workspace** — holds the subscription. The first org a user creates becomes their primary by default.
- **Secondary workspace** — any workspace beyond the primary in the same account. Inherits subscription state.

## User stories

### Onboarding
- As an existing paid customer on Growth, I can create a second workspace from a "Workspaces" tab in account settings without entering payment info again.
- The new workspace counts against my plan's workspace allowance (Growth = 2 included).
- If I exceed the allowance, I'm prompted to add a paid workspace add-on or upgrade tier.

### Day-to-day
- I can switch between workspaces via the org switcher.
- I can see pooled usage (X / 1,000 learners, Y / 10M AI tokens) and a per-workspace breakdown.
- A workspace admin (not the account owner) sees their workspace normally; billing UI is hidden or shows "Managed by [primary workspace name]".

### Billing
- The Stripe subscription lives on the primary workspace.
- One invoice lists: base plan + workspace add-ons + overages.
- If the primary workspace cancels or fails payment, **all** linked workspaces are affected (downgrade to free or readonly per existing policy).

### Downgrade / overage handling
- If a customer downgrades from Growth (2 included) to Starter (1 included) while having 2 workspaces:
  - All workspaces remain readable but lock to read-only until the customer either deletes a workspace or upgrades back.
  - 7-day grace period to resolve.
- If a customer exceeds pooled learner quota, existing per-tier overage policy applies.

### Edge: primary owner leaves the company
- Support can manually transfer subscription ownership to another admin in the primary workspace. Self-serve in v2.

## Functional requirements

### Data model (proposed)

**Option A — direct parent pointer (recommended for v1):**
```
organization.parentOrganizationId → organization.id (nullable)
```
- Primary = `parentOrganizationId IS NULL`
- All workspaces with same parent (or themselves as parent) belong to one account
- ✅ Minimal migration
- ⚠️ Reparenting requires updating all children

**Option B — explicit account table (cleaner long-term):**
```
account (id, stripe_customer_id, plan_id, created_at)
organization.account_id → account.id
```
- ✅ Cleaner billing semantics; future-proof for transfers
- ⚠️ Migration: every existing org needs an account row

**Recommendation: Option A for v1.** Migrate to Option B in v2 if data-model strain shows up.

### Subscription / billing
- One Stripe subscription per account, on the primary workspace.
- Subscription line items:
  - 1× base plan
  - N× workspace add-on (N = total workspaces − tier's included count, ≥ 0)
  - Overage line items
- Webhook handlers must propagate subscription state to all linked workspaces.

### Quota enforcement
- Learner count = SUM of active learners across all workspaces in account.
- AI token usage = SUM of tokens consumed across all workspaces in account.
- Quotas checked at the **account** level on every usage event.
- Per-workspace usage tracked for visibility, not enforced separately.

### Routes & API surface

**New endpoints:**
- `POST /account/workspaces` — create a secondary workspace (account-level auth required)
- `GET /account/workspaces` — list all workspaces in account with per-workspace usage
- `DELETE /account/workspaces/:id` — delete a secondary workspace (cannot delete primary while account exists)
- `POST /account/workspaces/:id/transfer-primary` — promote secondary to primary (v2)
- `GET /account/usage` — pooled usage breakdown

**Existing endpoints affected:**
- All `organization/*` endpoints already scope to the active workspace — no change
- Billing/subscription endpoints operate on the account/primary workspace

### Dashboard UI

1. **Workspace switcher** — existing; needs to scope to "workspaces in my account" plus invited-as-member orgs
2. **Account settings page** (new) — accessible from primary workspace only:
   - List of workspaces with status, learner count, AI usage
   - "Create workspace" button (tier-aware: "1 of 2 included" / "Add another for $79/mo")
   - Billing tab moved here from per-workspace settings (or aliased)
3. **Per-workspace settings** — billing UI hidden on secondary workspaces; shows "Billing managed by [primary workspace name]"
4. **Pooled usage banner** — in account settings: "1,247 of 5,000 active learners across 3 workspaces"

## Pricing logic

| Tier | Workspaces included | Extra workspace |
|---|---|---|
| Free | 1 | – (must upgrade) |
| Starter $49 | 1 | – (must upgrade) |
| Growth $149 | 2 | +$79/mo each |
| Business $399 | 3 | +$149/mo each |
| Enterprise | Unlimited | included |

- Extras prorate normally.
- Annual subscriptions: workspace add-ons priced at 10× monthly (2 months free), matching plan annual logic.

## Success metrics

- **Activation:** % of paid customers who create a 2nd workspace within 90 days. Target: 20% by month 6, 30% by month 12.
- **Expansion ARR lift:** `workspace_addon_mrr / base_plan_mrr`. Target: 10%+ blended lift.
- **Retention:** Net retention on customers with 2+ workspaces vs 1. Hypothesis: 2+ workspace customers churn ~50% less.
- **Support tickets:** No more than 1 ticket per 10 workspace creations in v1.

## Rollout plan

### v1 (4 weeks)
- Schema: add `parentOrganizationId` to `organization`
- Backend: secondary workspace endpoints, pooled quota enforcement, billing updates
- Dashboard: account settings page, workspace switcher tweak, pooled usage banner
- Marketing: ship "one account, multiple academies" homepage section
- Ship to existing paid customers first (manual feature flag), then GA

### v2 (post-launch, scope TBD)
- Self-serve "split workspace into own subscription"
- Cross-workspace analytics roll-up
- Account-level RBAC (single user as admin across all workspaces without per-org invites)
- Migrate to `account` table (Option B) if data model strain emerges

## Open questions

1. **Should free-tier users be able to create multiple workspaces?** Recommend: no (1-workspace cap).
2. **Quota fairness:** if Workspace A burns all the AI tokens, Workspace B has zero — do we expose per-workspace caps as an optional admin control? Recommend: not in v1.
3. **Are workspaces transferrable between accounts?** v1: no, manual support. v2: yes, with consent flow.
4. **Subdomain vs custom domain per workspace:** already supported per-org — confirm SSO/auth flows scope correctly.
5. **Billing edge case:** when adding a paid workspace add-on mid-cycle, prorate immediately or at next renewal? Recommend: immediate prorate (Stripe default).

## Risks

- **Confusing UX** if terminology isn't tight — pick one term ("workspace" or "academy") and use it everywhere
- **Quota gaming** — customers stuffing free workspaces; mitigated by 1-workspace cap on Free
- **Per-workspace SSO config** — each workspace's OIDC config is independent; confirm no cross-pollination of identities
- **Backwards compat** — existing orgs become primary by default; migration is a single backfill (no-op, NULL is already default)

## Out of scope

- Cross-workspace shared course library
- Account-level admin role separate from per-workspace admin
- Public marketplace of shared courses across accounts