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

# PRD — Tenant Tier System (Basic, Pro, Premium)

- Slug: `tenant-tiers`
- Date: `2026-03-03`
- Status: Draft

## Summary

Add tenant-wide tiers (Basic, Pro, Premium) alongside the existing license count model. Tiers control feature access — Basic restricts billing, projects, technician dispatch (and more later), showing an upsell placeholder. Existing customers are grandfathered into Pro. The tier source evolves over three horizons: Stripe product mapping → new Stripe products per tier → internal contracts system.

**Design principle**: The `plan` column on the `tenants` table is the **single source of truth** for a tenant's tier. The gating infrastructure only reads this column. What *writes* it changes over time, but the read side stays stable.

## Problem

Currently all tenants have equal access to all features regardless of their subscription level. There is no mechanism to:
- Differentiate feature access between free/trial and paying customers
- Offer a tiered product (Basic → Pro → Premium) with progressive feature unlock
- Show upgrade prompts when users encounter gated features
- Map Stripe products to feature tiers automatically

## Goals

1. Define three tiers (Basic, Pro, Premium) with a clear feature-to-tier mapping
2. Gate features at navigation, page, and server-action levels
3. Backfill all existing tenants to Pro (grandfathered)
4. Map Stripe products to tiers so new tenants get the correct tier automatically
5. Show upsell placeholders on gated features directing users to upgrade
6. Deploy in phases with zero disruption to production
7. Design for future horizons: new Stripe products per tier → internal contracts system

## Non-goals

- Tier upgrade/downgrade self-service flow (Horizon 2)
- Internal contracts managing tiers (Horizon 3)
- Pricing page or public tier comparison
- Per-feature billing or usage-based gating
- Admin UI for managing tier-to-feature mappings
- Monitoring, metrics, or analytics for tier usage

## Users and Primary Flows

### Personas

1. **Existing MSP customer** — Currently using all features. After deployment, sees no change (grandfathered to Pro).
2. **New EE customer via Stripe** — Signs up through NM-Store checkout. Tier is resolved from Stripe product (`alga-psa-preview` → Pro).
3. **CE self-registration user** — Registers without Stripe. Gets Pro (no gating in CE).
4. **Basic-tier tenant** (future) — Sees core features only. Billing, Projects, Technician Dispatch are hidden. Upsell placeholders guide to upgrade.

### Primary Flows

1. **Login → Session loads tier from JWT → TierProvider makes it available client-side**
2. **Navigate sidebar → Items filtered by tier → Gated items hidden**
3. **Direct URL to gated page → UpsellPlaceholder shown instead of content**
4. **Server action on gated feature → TierAccessError thrown**
5. **Stripe product change → Webhook updates `tenants.plan` → Session refreshes within 5 min (or instant via `refreshTier()`)**

## UX / UI Notes

- **Navigation**: Gated items are hidden from sidebar (not grayed out)
- **Page-level**: Full-page `UpsellPlaceholder` with icon, heading ("{Feature} requires {Tier Label}"), description, and CTA button linking to `/msp/account`
- **Misconfigured state**: Warning banner ("Subscription not configured — contact support") when `plan` is NULL/invalid
- **Account page**: Shows current tier badge, tier comparison card, upgrade action

## Requirements

### Functional Requirements

#### FR1: Tier Constants & Type System
- Three tiers: `basic`, `pro`, `premium` as const tuple
- `TenantTier` type derived from the tuple
- `resolveTier(plan)` returns `{ tier, isMisconfigured }` — NULL → basic + misconfigured flag
- `isValidTier()` type guard
- `TIER_LABELS` for display names

#### FR2: Tier-to-Feature Mapping
- `TIER_FEATURES` enum: `BILLING`, `PROJECTS`, `TECHNICIAN_DISPATCH`, `EXTENSIONS` (extensible)
- `TIER_FEATURE_MAP`: basic = [], pro = [BILLING, PROJECTS, TECHNICIAN_DISPATCH], premium = [...pro, EXTENSIONS]
- `tierHasFeature(tier, feature)` → boolean
- `FEATURE_MINIMUM_TIER` reverse mapping

#### FR3: ITenant Interface Update
- Narrow `plan?: string` to `plan?: TenantTier` in both interface locations

#### FR4: Registration Flow
- Both `Tenant.insert` calls in `useRegister.tsx` set `plan: 'pro'`
- CE tenants always get Pro (never gated)

#### FR5: Migration Backfill
- All existing tenants with NULL or empty plan → `'pro'`
- No column default — NULL is intentional error state

#### FR6: Test Data Fix
- `testDataFactory.ts`: change `plan: 'test'` → `plan: 'pro'`

#### FR7: Session Integration
- `plan` field added to JWT, Session.user, User, ExtendedUser interfaces
- JWT callback fetches plan on initial sign-in
- Throttled refresh every 5 minutes on subsequent requests
- Session callback propagates plan to client

#### FR8: Client-Side Tier Context
- `TierProvider` wraps app inside `AppSessionProvider`
- `useTier()` hook: tier, isMisconfigured, isBasic, isPro, isPremium, hasFeature(), refreshTier()

#### FR9: Stripe Product → Tier Mapping
- `STRIPE_PRODUCT_TIER_MAP` config: `alga-psa-preview` → pro, future products pre-mapped
- `tierFromStripeProduct()` function, unknown products default to pro

#### FR10: Tenant Creation Workflow Integration
- `createTenantInDB()` resolves tier from Stripe price → sets `tenantData.plan`
- Covers: Stripe checkout, Nine Minds extension, Provisioning API (all same Temporal workflow)

#### FR11: Checkout Webhook Integration
- `handleCheckoutCompleted()` and `handleSubscriptionUpdated()` resolve product → tier → update `tenants.plan`

#### FR12: Upsell Placeholder Component
- Full-page placeholder: icon, heading, description, CTA to `/msp/account`

#### FR13: TierGate Components
- Client-side `TierGate` wrapper (uses TierContext)
- Server-side `ServerTierGate` (reads session directly)

#### FR14: Navigation Gating
- `requiredFeature` field on `MenuItem` interface
- Sidebar filters items by tier
- Gated: Billing → BILLING, Projects → PROJECTS, Technician Dispatch → TECHNICIAN_DISPATCH

#### FR15: Page-Level Gating
- Billing, Projects, Technician Dispatch pages wrapped with gate components

#### FR16: Server Action Gating
- `assertTierAccess(tenant, feature)` throws `TierAccessError` if tier lacks feature
- Applied to billing, project, technician dispatch server actions

#### FR17: Account Page Enhancement
- Replace hardcoded `plan_name: 'Professional'` with actual tier
- Add tier badge, tier comparison card, upgrade action

### Non-functional Requirements

- Zero disruption deployment — Phase A changes nothing visible, Phase B deployed while all tenants are Pro
- Session plan refresh throttled to 5-minute intervals (avoids DB queries on every request)
- Pure TypeScript tier config — no DB or PostHog dependency for feature mapping

## Data / API / Integrations

- **Database**: `tenants.plan` column (varchar, already exists, nullable — NULL = error state)
- **Stripe**: Product name → tier mapping via `STRIPE_PRODUCT_TIER_MAP`
- **NextAuth**: JWT carries `plan` and `last_plan_check` fields
- **Temporal**: `createTenantInDB()` sets plan from Stripe product

## Security / Permissions

- Server-side `assertTierAccess()` prevents API-level bypass of client gating
- Tier is read from DB in server actions, not trusted from client

## Rollout / Migration

### Phase A: Foundation (deploy first, no behavior change)
- Migration backfills all tenants to Pro
- Session carries tier info
- TierProvider available but everyone is Pro — no visible change

### Phase B: Gating Infrastructure (deploy second, still no behavior change)
- Gate components, navigation filtering, server action guards deployed
- Since all tenants are Pro, no one is gated

### Phase C: EE Registration Gating (deploy when ready)
- EE self-registration sets `plan: 'basic'` (CE stays `'pro'`)

## Open Questions

None — all questions resolved during planning:
- NULL plan handling: error state (basic access + warning banner)
- CE mode: always Pro, never gated
- Dev seeds: already set `plan: 'pro'`
- Nine Minds extension: same Temporal workflow, covered by A9
- Test factory: updated to `'pro'`

## Acceptance Criteria (Definition of Done)

1. All existing production tenants have `plan = 'pro'`
2. New tenants via Stripe checkout get tier resolved from product
3. JWT contains `plan` field, refreshed every 5 minutes
4. Basic-tier tenant sees gated features hidden from sidebar
5. Direct navigation to gated page shows upsell placeholder
6. Server actions on gated features throw TierAccessError
7. Account page shows actual tier (not hardcoded 'Professional')
8. CE self-registration creates tenants with `plan = 'pro'`
9. NULL plan shows warning banner + basic-level access