PSA/ee/docs/plans/2026-03-26-solo-tier/PRD.md

# PRD — Solo Tier

- Slug: `solo-tier`
- Date: `2026-03-26`
- Status: Draft

## Summary

Add a **Solo** tier below Pro for single-user hosted EE customers. Solo gets core PSA functionality at a flat-rate Stripe subscription (no per-user fee), limited to 1 user. AI is a cross-tier paid add-on (not bundled with any tier). Mobile app access is gated to Pro+.

Tier hierarchy: **Solo < Pro < Premium**. CE build is unaffected.

## Problem

New single-user MSP operators or freelancers need an affordable entry point into Alga PSA. The current Pro tier (base + per-user pricing) is priced for teams. There's no way to offer a stripped-down, single-user plan without creating a new tier.

Additionally, AI capabilities have different cost structures than core features and should be purchasable independently of tier level, allowing any customer to add AI when they need it.

## Goals

1. Introduce a Solo tier that provides core PSA functionality for 1 user at a flat rate
2. Gate Pro+ features (integrations, extensions, SSO, managed email, advanced assets, client portal admin, workflow designer, mobile access) behind tier checks
3. Make AI & Chat a purchasable add-on for any tier (Solo, Pro, Premium) — first activation of the add-on system
4. Block Solo users from mobile app authentication
5. Support Stripe checkout, upgrade (Solo->Pro), and downgrade (Pro->Solo) flows
6. Enforce 1-user license limit for Solo
7. Zero impact on existing Pro/Premium tenants or CE build

## Non-goals

- Changing the CE build behavior (all features remain unlocked in CE)
- Database migration for existing tenants (no plan column changes needed)
- Per-feature add-on store beyond AI (future work)
- Mobile app changes beyond blocking auth (no Solo-specific mobile UI)
- Monitoring/observability/metrics for tier usage
- Admin dashboard for tier management

## Users and Primary Flows

### Personas

1. **Solo user (new signup)**: Freelance MSP / solo technician signing up for Alga PSA. Wants tickets, billing, scheduling, basic asset management. May later want AI or to grow the team (upgrade to Pro).
2. **Pro user considering downgrade**: Existing Pro user who is the only active user and wants to save money by dropping to Solo.
3. **Any-tier user wanting AI**: Customer on any plan who wants to purchase the AI Assistant add-on.

### Primary Flows

**F1 — Solo signup & checkout**
1. New user selects Solo plan during signup
2. Stripe checkout creates single line item (base price only, no per-user) with 7-day trial
3. Tenant created with `plan = 'solo'`, trial active for 7 days
4. User logs in → sees core PSA features, sidebar hides Extensions, settings tabs show upgrade CTAs for gated features

**F2 — Solo user hits gated feature**
1. Solo user navigates to Settings → Integrations tab
2. Tab is visible but content replaced with `<FeatureUpgradeNotice>` showing upgrade CTA
3. If user tries gated API route directly, server returns tier access error

**F3 — Solo user tries mobile app**
1. Solo user attempts to set up mobile app (scan QR / enter OTT)
2. OTT exchange returns 403 with "Mobile app access requires Pro or higher"
3. Web UI optionally shows upgrade CTA on mobile setup page

**F4 — Upgrade Solo -> Pro**
1. Solo user clicks "Upgrade to Pro" in Account Management
2. Stripe subscription updated: per-user line item added, base price swapped
3. Tier refreshes immediately → all Pro features unlock

**F4b — Solo -> Pro trial (established customers)**
1. Established Solo customer (past their 7-day Solo trial) clicks "Try Pro free"
2. Pro trial activated for 15–30 days (duration TBD) — all Pro features unlock
3. At trial end, customer reverts to Solo unless they convert to paid Pro
4. Not available if customer is still in their Solo trial period (prevents trial stacking)

**F5 — Downgrade Pro -> Solo**
1. Pro user with exactly 1 active user clicks "Downgrade to Solo"
2. System validates user count = 1
3. Stripe subscription updated: per-user item removed, base price swapped
4. If user count > 1, downgrade blocked with message

**F6 — Purchase AI add-on (any tier)**
1. User clicks "Add AI Assistant" in Account Management
2. Stripe creates separate subscription item for AI add-on
3. `tenant_addons` row inserted → AI features unlock immediately
4. AI chat, document AI, AI sidebar, workflow AI all become available

**F7 — Cancel AI add-on**
1. User clicks "Cancel AI Assistant" in Account Management
2. Stripe removes AI line item
3. `tenant_addons` row deactivated → AI features disabled

**F8 — Solo user tries to add second user**
1. Solo admin goes to Settings → Users → "Add User"
2. Button disabled with message: "Solo plan is limited to 1 user. Upgrade to Pro to add more users."
3. Server-side enforcement also rejects the action if bypassed

## UX / UI Notes

- **Sidebar**: Menu items with `requiredFeature` are hidden (not greyed out) for Solo users — Extensions and Workflow Editor disappear from nav
- **Settings tabs**: Gated tabs (Integrations, Extensions, Email) remain visible and clickable, but content replaced with `<FeatureUpgradeNotice>` component showing the required tier and an upgrade button
- **Account Management**: Shows current tier with Solo-specific messaging ("Your Solo plan includes core PSA features. Upgrade to Pro for integrations, mobile access, and more."). AI add-on section is separate from tier upgrade flow, showing "Add AI Assistant" or "AI Assistant (active)" status
- **Add User button**: Disabled with tooltip/CTA when `isSolo`

## Requirements

### Functional Requirements

#### Phase 1: Core Type System
- R1.1: Add `'solo'` to `TENANT_TIERS` array and `TenantTier` type
- R1.2: Add `TIER_RANK` mapping: `{ solo: 0, pro: 1, premium: 2 }`
- R1.3: Add `tierAtLeast(tier, minimum)` helper using rank comparison
- R1.4: Add 8 new `TIER_FEATURES` entries: INTEGRATIONS, EXTENSIONS, MANAGED_EMAIL, SSO, ADVANCED_ASSETS, CLIENT_PORTAL_ADMIN, WORKFLOW_DESIGNER, MOBILE_ACCESS (all min tier: `pro`)
- R1.5: Rewrite `tierHasFeature()` to use rank comparison instead of map lookup
- R1.6: Derive `TIER_FEATURE_MAP` from `FEATURE_MINIMUM_TIER` + `TIER_RANK`
- R1.7: Add `AI_ASSISTANT` to `ADD_ONS` enum with labels and descriptions
- R1.8: `resolveTier()` defaults to `'pro'` for null/invalid (Solo is opt-in only)

#### Phase 1b: Add-On Wiring
- R1b.1: Create `getActiveAddOns(tenantId)` service querying `tenant_addons` table
- R1b.2: Create `assertAddOnAccess(addOn)` server-side check, similar to `assertTierAccess()`
- R1b.3: Wire AI add-on Stripe products with env vars for monthly/annual pricing

#### Phase 2: Context & Session
- R2.1: Add `isSolo` boolean to `TierContextValue`
- R2.2: Add `addOns` array and `hasAddOn()` helper to `TierContextValue`
- R2.3: CE bypass unchanged — Solo restrictions are EE-only

#### Phase 3: Sidebar & Navigation Gating
- R3.1: Add `requiredFeature` to `MenuItem` interface
- R3.2: Annotate Extensions and Workflow Editor menu items with their required features
- R3.3: Filter sidebar items where `requiredFeature` is set and tier doesn't have it (recursive for subItems)

#### Phase 4: Settings Tab Gating
- R4.1: Add `requiredFeature` to `TabContent` type in SettingsPage
- R4.2: Tag Integrations, Extensions, Email tabs with their required features
- R4.3: Render `<FeatureUpgradeNotice>` instead of content when feature is gated
- R4.4: Settings sidebar items remain visible (no hiding, only content gating)

#### Phase 5: EE Route Handler Tier Checks
- R5.1: Add `assertTierAccess()` to ~20 EE route handlers for tier features
- R5.2: Add `assertAddOnAccess(ADD_ONS.AI_ASSISTANT)` to AI routes (chat, document-assist, etc.)
- R5.3: Gate client components with `<TierGate>` / `useTierFeature()` / `hasAddOn()`

#### Phase 5b: Mobile Access Gating
- R5b.1: Check tenant tier in `exchangeOttForSession()` — reject Solo with 403
- R5b.2: Return upgrade message in error response for Solo mobile auth attempts

#### Phase 6: Stripe Integration
- R6.1: Add `'alga-psa-solo': 'solo'` to stripe tier mapping
- R6.2: Solo checkout: single line item (base only), `userPriceId: null`, with 7-day trial
- R6.3: Solo webhook handling: set `licensed_user_count = 1` when no per-user item
- R6.4: `upgradeTier()`: Solo -> Pro adds per-user line item
- R6.5: New `downgradeTier()`: Pro -> Solo validates user count = 1, removes per-user item
- R6.6: AI add-on purchase/cancel creates/removes separate subscription item
- R6.7: AI webhook activates/deactivates `tenant_addons` row
- R6.8: Solo->Pro trial: activate Pro features for 15–30 days for established Solo customers (not during Solo trial). Revert to Solo at trial end if not converted.

#### Phase 7: License Enforcement
- R7.1: Block adding users when Solo and `used >= 1`
- R7.2: Disable "Add User" button in UI with upgrade CTA for Solo

#### Phase 8: AccountManagement UI
- R8.1: Add display names for 8 new tier features
- R8.2: Solo-specific messaging on account page
- R8.3: "Upgrade to Pro" card for Solo tenants
- R8.4: "Downgrade to Solo" option for Pro tenants with 1 user
- R8.5: AI add-on purchase/status card (separate from tier flow)

### Non-functional Requirements

- Existing Pro/Premium tenants must experience zero behavior change (except AI now requires add-on)
- CE build must remain fully unlocked regardless of tier or add-ons
- `resolveTier()` must default to Pro for any null/invalid plan (backward compatibility)
- Type system changes must pass `npm run build:shared`

## Data / API / Integrations

**Database**: No migration needed. `tenants.plan` is already an unconstrained text column. `tenant_addons` table already exists (created via migration `20260303100000`).

**Stripe**: New price IDs for Solo base (monthly/annual) and AI add-on (monthly/annual). No new Stripe products needed — just new prices under existing product.

**Session**: `session.user.plan` already carries the plan string. Add-ons will be fetched from DB per-request or added to session.

## Security / Permissions

- Tier checks are runtime-only (not build-time) — `isEnterprise` check is untouched
- Server-side enforcement via `assertTierAccess()` and `assertAddOnAccess()` prevents API bypass
- Mobile auth blocked at OTT exchange level — Solo users never receive API tokens
- License limit enforced server-side in `addUser` action

## Rollout / Migration

- No database migration required
- All existing tenants keep `plan = 'pro'` (grandfathered)
- Solo is opt-in only — new signups or manual downgrades
- Feature flag `'tier-upgrade-flow'` already gates upgrade UI — extend for Solo
- AI add-on: existing Pro/Premium tenants need awareness that AI is now separately purchased (comms/migration strategy TBD by product team)

## Open Questions

1. ~~**AI add-on rollout for existing tenants**~~ — RESOLVED: No grandfathering. AI is new — nobody has it yet. It's addon-only from day one for all tiers.
2. ~~**Solo trial**~~ — RESOLVED: 7-day free trial for new Solo purchases.
3. **AI add-on pricing**: Monthly/annual Stripe price IDs to be added later. Implementation should support the env vars but they won't be populated at launch.
4. ~~**Solo -> Pro upgrade trial**~~ — RESOLVED: Established Solo customers (past their initial 7-day trial) can trial Pro features. Duration TBD — either 15 or 30 days. Not available during the Solo trial period itself.

## Acceptance Criteria (Definition of Done)

1. `npm run build:shared` passes with new tier/feature/add-on types
2. Existing Pro tenant login — no behavior change, all tier features available
3. Solo tenant — sidebar hides gated items, settings tabs show upgrade CTAs, EE API routes return tier error
4. AI add-on — disabled without add-on for any tier; enabled when `tenant_addons` row active
5. Mobile — Solo OTT exchange returns 403; Pro/Premium succeeds
6. License — Solo cannot add second internal user
7. Stripe — Solo checkout has single line item; upgrade adds per-user; downgrade removes it
8. AI add-on — separate Stripe item; webhook creates/removes `tenant_addons` row
9. CE build — all features unlocked regardless of tier/add-ons
10. All unit tests pass (`npm run test:unit`)