PSA/ee/docs/plans/2026-03-03-tenant-tier-system/SCRATCHPAD.md

Scratchpad — Tenant Tier System

• Plan slug: tenant-tiers
• Created: 2026-03-03
• Updated: 2026-03-05 (narrowed to 2-tier model: Pro/Premium)

What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.

Decisions

• (2026-03-05) 2-tier model only: Pro and Premium. No basic tier — users who want only basic features can run the open-source CE. This simplifies the tier system significantly.
• (2026-03-05) Existing customers grandfathered at Pro with $0 base fee. They keep full access to all standard features.
• (2026-03-05) Invoice Designer is the POC gated feature. Only premium tenants get the visual drag-and-drop designer. Code view remains available to all.
• (2026-03-05) Add-ons infrastructure built. tenant_addons table + constants/utilities ready for future per-tenant purchasable features.
• (2026-03-05) Phase C removed. There's no basic tier to gate self-registration into.
• (2026-03-03) NULL plan → error state (pro access + warning banner), NOT a lower tier. Rationale: prevents accidentally restricting features for misconfigured customers.
• (2026-03-03) No DB column DEFAULT on plan. NULL is intentional error state caught by the UI.
• (2026-03-03) CE tenants always get plan: 'pro' — CE has no Stripe/tiers, should never be gated.
• (2026-03-03) Temporal workflow updated in Phase A (not deferred). All EE tenant creation paths funnel through createTenantInDB().
• (2026-03-03) Pre-map future Stripe product names (alga-psa-pro, alga-psa-premium) so they work automatically when created.
• (2026-03-03) Three horizons: (1) Stripe product mapping now, (2) new Stripe products per tier later, (3) internal contracts way later.
• (2026-03-03) Plan throttle at 5 min (separate from session revocation check at 30s).

Discoveries / Constraints

• (2026-03-03) ITenant already has plan?: string field — just needs narrowing to TenantTier.
• (2026-03-03) Tenant.updatePlan(knex, tenant, plan) already exists in packages/db/src/models/tenant.ts.
• (2026-03-03) Dev seeds at server/seeds/dev/01_tenants.cjs already set plan: 'pro' — no change needed.
• (2026-03-03) Test factory at server/test-utils/testDataFactory.ts sets plan: 'test' — needs update to 'pro'.
• (2026-03-03) Two buildAuthOptions paths in nextAuthOptions.ts — BOTH must be updated (enterprise and non-enterprise).
• (2026-03-03) Nine Minds reporting extension → /api/v1/tenant-management/create-tenant → Temporal workflow → createTenantInDB(). Same path as Stripe checkout.
• (2026-03-03) Provisioning API (/api/provisioning/tenants) also uses Temporal workflow. Same path.
• (2026-03-03) CE AccountManagement stub returns null. Account page enhancements are EE-only.
• (2026-03-03) isEnterprise check in server/src/lib/features.ts uses EDITION / NEXT_PUBLIC_EDITION env vars.
• (2026-03-03) Existing FeaturePlaceholder component shows "under construction" — distinct from new UpsellPlaceholder.
• (2026-03-03) License count gating uses if (limit !== null && used >= limit) — NULL = no limit. Tier gating is additive.

Commands / Runbooks

• Verify migration: SELECT tenant, plan FROM tenants WHERE plan IS NULL OR plan = ''; (should return 0 rows after migration)
• Test misconfigured state: UPDATE tenants SET plan = NULL WHERE tenant = '<test-tenant-id>';
• Test premium gating: UPDATE tenants SET plan = 'premium' WHERE tenant = '<test-tenant-id>';
• Inspect JWT: Browser DevTools → Application → Cookies → next-auth.session-token → decode at jwt.io
• Force session refresh: Call refreshTier() from TierContext or wait 5 min

Links / References

• Detailed design reference: .ai/tiers/tenant-tier-system-plan.md
• Tenant model: packages/db/src/models/tenant.ts
• Auth types: packages/auth/src/types/next-auth.ts
• Auth options: packages/auth/src/lib/nextAuthOptions.ts
• Layout client: server/src/app/msp/MspLayoutClient.tsx
• Tenant operations: ee/temporal-workflows/src/db/tenant-operations.ts
• Stripe service: ee/server/src/lib/stripe/StripeService.ts
• Account management: ee/server/src/components/settings/account/AccountManagement.tsx
• Registration: packages/auth/src/actions/useRegister.tsx
• Edition check: server/src/lib/features.ts
• Dev seeds: server/seeds/dev/01_tenants.cjs
• Test factory: server/test-utils/testDataFactory.ts

Tenant Creation Paths Coverage

Path	How Plan Is Set	Phase
Stripe checkout → Temporal workflow	createTenantInDB() resolves tier from Stripe product	A
Nine Minds reporting extension	Same Temporal workflow → same createTenantInDB()	A
Provisioning API	Same Temporal workflow	A
CE self-registration (useRegister.tsx)	plan: 'pro' in Tenant.insert()	A
Dev seeds	Already plan: 'pro'	—
Test data factory	plan: 'test' → plan: 'pro'	A
Migration backfill	NULL/empty → 'pro'	A

Implementation Log

Phase A Complete (2026-03-03)

• Created packages/types/src/constants/tenantTiers.ts with TENANT_TIERS ['pro', 'premium'], TenantTier, TIER_LABELS, isValidTier(), resolveTier()
• Created packages/types/src/constants/tierFeatures.ts with TIER_FEATURES enum (INVOICE_DESIGNER), TIER_FEATURE_MAP, tierHasFeature(), FEATURE_MINIMUM_TIER
• Created packages/types/src/constants/addOns.ts with ADD_ONS enum (empty placeholder), tenantHasAddOn()
• Updated ITenant.plan to use TenantTier type in both interface files, added addons?: string[]
• Updated useRegister.tsx to set plan: 'pro' in both Tenant.insert() calls
• Created backfill migration: 20260303100000_backfill_tenant_plan_to_pro.cjs
• Created add-ons table migration: 20260305100000_create_tenant_addons.cjs
• Updated testDataFactory.ts: plan 'test' → 'pro'
• Updated next-auth types with plan in User, Session.user, and JWT interfaces
• Updated ExtendedUser interface in nextAuthOptions.ts
• Added plan fetching on initial sign-in in both buildAuthOptions paths
• Added 5-minute throttled plan refresh in JWT callback
• Added plan propagation from JWT to session in session callback
• Created TierContext with TierProvider and useTier() hook
• Wrapped MspLayoutClient content with TierProvider
• Created stripeTierMapping.ts with STRIPE_PRODUCT_TIER_MAP and tierFromStripeProduct()
• Wired tier resolution in createTenantInDB() from Stripe product
• Updated handleCheckoutCompleted() and handleSubscriptionUpdated() to set tenant plan

Phase B Complete (2026-03-03)

• Created UpsellPlaceholder in packages/ui/src/components/tier-gating/UpsellPlaceholder.tsx with icon, heading, description, CTA to /msp/account
• Created TierGate client component in server/src/components/tier-gating/TierGate.tsx using TierContext
• Created ServerTierGate in server/src/lib/tier-gating/ServerTierGate.tsx reading session directly
• Created assertTierAccess utility with TierAccessError class in server/src/lib/tier-gating/assertTierAccess.ts
• Applied assertTierAccess to invoice template save/delete actions (invoiceTemplates.ts)
• Gated Invoice Designer visual tab in InvoiceTemplateEditor with canUseVisualDesigner prop
• Computed canUseVisualDesigner server-side in billing page from session tier
• Updated AccountManagement to use useTier() hook for tier display
• Added tier badge with TIER_LABELS[tier] to account page
• Added tier features list showing TIER_FEATURE_MAP[tier] features

Tests Implemented (2026-03-03)

• T001-T011: Tier constants unit tests in packages/types/src/constants/tenantTiers.test.ts
• T012-T017: Tier features unit tests in packages/types/src/constants/tierFeatures.test.ts
• T018: Export verification in packages/types/src/constants/tierExports.test.ts
• T019: ITenant.plan type check in packages/types/src/interfaces/tenant.interface.typecheck.test.ts
• T020: Test data factory check in server/src/test/unit/testDataFactory.test.ts
• T021-T024: Stripe tier mapping tests in ee/server/src/__tests__/unit/stripeTierMapping.test.ts
• T025-T027: assertTierAccess tests in server/src/lib/tier-gating/assertTierAccess.test.ts
• Total: 28 unit tests implemented and passing (verified with vitest run)

Remaining Tests (Integration/E2E)

The remaining tests require:

• Database connections for migration tests
• NextAuth session mocking for JWT/session tests
• React component rendering for UI tests
• Playwright for E2E tests These are out of scope for initial unit test coverage and should be implemented as integration tests.

Open Questions

• (resolved) NULL plan handling → error state with pro access + warning banner
• (resolved) CE mode → always Pro, never gated
• (resolved) Dev seeds → already set plan: 'pro'
• (resolved) Nine Minds extension → same Temporal workflow, covered by A8/A9
• (resolved, 2026-03-05) No basic tier → users wanting basic features use open-source CE